MATLAB自动化测试：基于Jenkins构建矩阵的CI/CD实践指南

1. 项目概述：当“矩阵实验室”遇上“构建矩阵”

看到这个标题，你可能会心一笑。没错，这玩的是一个经典的双关梗。一方面，它指向了那个在科学计算和工程领域如雷贯耳的名字——MATLAB（Matrix Laboratory，矩阵实验室）。另一方面，它又巧妙地融入了现代软件工程的核心实践之一：持续集成/持续交付（CI/CD）中的“构建矩阵”（Build Matrix）。这个项目，或者说这个思路，探讨的正是如何将MATLAB这类传统上被视为“桌面科研工具”的软件，纳入到以Jenkins等工具为代表的现代化、自动化软件构建与测试流水线中。这不仅仅是两个技术名词的简单拼接，它背后反映的是一个非常现实的需求：在算法研究、模型开发日益工程化、团队化的今天，如何确保那些在MATLAB里诞生的宝贵代码，能够像我们熟悉的Java、Python项目一样，被可靠地构建、测试和部署。

我遇到过太多这样的场景了：一个博士或算法工程师在MATLAB里呕心沥血调试出一个完美的信号处理模型或控制算法，仿真结果漂亮得无可挑剔。但当需要将其集成到更大的软件系统、交付给客户，或者仅仅是让团队另一个成员复现时，问题就来了。“你的MATLAB是什么版本？”“用了哪个工具箱？”“这个.m脚本的依赖路径怎么设？”诸如此类的问题会迅速消耗掉协作的热情。更棘手的是，随着项目迭代，你根本无法保证今天能跑通的脚本，三个月后换了台新电脑或者更新了MATLAB版本后还能正常工作。这就是“构建矩阵实验室”要解决的核心痛点：为MATLAB代码建立一套可重复、自动化、多环境验证的构建与测试体系。

简单来说，它要做的事情是：利用Jenkins的“构建矩阵”等特性，自动地在多个预配置的环境（例如，不同版本的MATLAB，搭配不同的操作系统或工具箱组合）中，执行你的MATLAB代码的测试套件，确保其兼容性与正确性。这听起来可能有点“杀鸡用牛刀”，但对于那些对结果准确性要求极高、或需要长期维护的科研与工程项目而言，这种投入是绝对值得的。接下来，我将为你彻底拆解如何搭建这样一个“实验室”，从设计思路到避坑细节，一一道来。

2. 核心架构与工具选型解析

搭建一个针对MATLAB的CI/CD流水线，工具选型是第一步，也是最需要深思熟虑的一步。这不仅仅是选择一个构建服务器那么简单，而是需要构建一整套能够与MATLAB这个“封闭花园”进行交互的生态系统。

2.1 为什么是Jenkins？

在众多CI/CD工具中（如GitLab CI, GitHub Actions, TeamCity等），Jenkins仍然是这个场景下一个非常强大且灵活的选择，尤其是考虑到“构建矩阵”的需求。Jenkins的“Matrix Project”或“Multi-configuration project”功能，天生就是为了在多维度组合（如操作系统、运行时版本、环境变量）下执行同一套构建流程而设计的。这对于需要测试MATLAB代码在R2021a vs R2023b，或者Windows vs Linux下的表现，是再合适不过的了。

此外，Jenkins的插件生态极其丰富。虽然可能没有官方的“MATLAB插件”，但通过其强大的命令行调用、文件操作和报告收集能力，我们可以通过组合其他插件（如SSH插件用于远程执行、Email Extension用于通知、Workspace Cleanup用于清理）来实现复杂的需求。Jenkins的分布式构建能力也很有用，你可以在专门安装了MATLAB的Windows代理节点上运行测试，而在Linux主节点上进行调度和报告汇总。

当然，Jenkins的缺点也很明显：它需要自己维护和配置，相比云原生的GitHub Actions等方案更重。但对于企业内网环境、或需要对构建环境有完全控制权（比如安装特定版本的MATLAB许可管理器）的场景，Jenkins提供的自由度是无与伦比的。

2.2 MATLAB的“无头”模式与自动化接口

要让MATLAB在无人值守的CI服务器上运行，关键是要让它“安静”地工作。MATLAB提供了几种方式：

1. 命令行启动与-batch选项：这是最核心的方式。通过命令matlab -batch "yourScript"，MATLAB会启动、执行脚本中的命令，然后自动退出。这是CI流水线的基石。
2. MATLAB运行时（MCR）与编译器：如果你最终需要交付的是独立应用程序或库，MATLAB Compiler可以将你的代码打包，并依赖免费的MATLAB Runtime来执行。这在CI中可以用来构建和测试打包后的产物。
3. MATLAB单元测试框架：从R2013a开始，MATLAB提供了基于类的单元测试框架。你可以编写matlab.unittest.TestCase类，这是实现自动化测试的关键。测试运行器可以输出详细的结果，这些结果可以被CI工具捕获并解析。

注意：许多人在尝试自动化时，会使用-r选项（如matlab -r "yourScript; exit;"）。在较新版本中，-r已被标记为不推荐使用（deprecated），官方推荐使用-batch。-batch选项会自动处理启动、执行、异常处理和退出，行为更可控，是CI环境下的首选。

2.3 辅助工具链

除了Jenkins和MATLAB本体，还需要一些辅助工具来让流程更顺畅：

• 版本控制系统：毫无疑问是Git。你的MATLAB代码、测试用例以及Jenkins的Pipeline脚本（Jenkinsfile）都应该纳入版本管理。
• 脚本语言：在Jenkins的Pipeline中，你会大量使用Shell（Linux）或Batch/PowerShell（Windows）来调用MATLAB命令。对于复杂的逻辑，也可以用Python来编写预处理或结果解析脚本。
• 依赖管理（可选但推荐）：对于大型项目，可以考虑使用MATLAB自带的“项目管理”功能，或第三方工具来管理工具箱依赖，但这在CI中通常通过确保构建节点安装了正确的工具箱版本来解决。

3. 构建环境准备与MATLAB配置

这一节是实操的起点，也是最容易踩坑的地方。我们的目标是在一台或多台机器上，为Jenkins准备好可以自动化执行MATLAB命令的环境。

3.1 Jenkins节点的MATLAB安装

假设我们使用Jenkins的“主从”架构，将构建任务分发到安装了MATLAB的“代理节点”上执行。

1. 静默安装MATLAB：在CI节点上，我们通常不希望进行交互式安装。MathWorks提供了静默安装方式。你需要准备一个installer_input.txt文件，其中包含安装路径、产品列表（如MATLAB, Simulink, 特定工具箱）、许可证文件路径等信息。然后通过安装程序配合-inputFile参数进行安装。这对于通过Docker镜像或系统镜像快速部署构建节点至关重要。

   # 示例命令（Linux） ./install -inputFile /path/to/installer_input.txt -mode silent

2. 许可证配置：这是核心挑战。CI服务器需要能够自动获取MATLAB许可证。

   • 网络许可证：最常见的方式。在节点上配置LM_LICENSE_FILE或MLM_LICENSE_FILE环境变量，指向公司的许可证服务器。确保Jenkins服务运行的用户有权限访问该服务器。
   • 文件许可证：可以将许可证文件放置在节点固定位置，并在安装时指定。但需注意许可证的绑定机制。
   • 重要提示：务必测试在Jenkins服务账户（如jenkins用户）下，能否成功通过命令行启动MATLAB并获取许可。最好写一个简单的测试脚本放入CI流程的第一步。

3. 环境变量与PATH：确保MATLAB的可执行文件路径（例如C:\Program Files\MATLAB\R2023b\bin或/usr/local/MATLAB/R2023b/bin）被添加到系统的PATH环境变量中。这样在Jenkins的Pipeline脚本中，才能直接使用matlab命令。

3.2 创建Jenkins Pipeline项目

在Jenkins中，我们选择使用“Pipeline”项目类型，因为它将构建流程以代码（Jenkinsfile）的形式定义，易于版本控制和复用。

1. 新建Item：选择“Pipeline”，给它起个名字，比如matlab-matrix-build。
2. Pipeline定义：选择“Pipeline script from SCM”。将你的Git仓库地址填入，并指定Jenkinsfile的路径（默认为根目录下的Jenkinsfile）。这意味着你的构建逻辑将和源代码一起管理。
3. 配置代理节点：在Pipeline脚本中，你可以通过agent指令指定在哪个标签的节点上运行。例如，你可以为所有安装了MATLAB R2023b的Windows节点打上matlab-r2023b-win的标签。

4. 编写核心Pipeline脚本（Jenkinsfile）

这是整个“构建矩阵实验室”的大脑。我们将编写一个声明式的Jenkinsfile，它定义了从检出代码到执行测试的全流程。

4.1 定义构建矩阵

我们使用matrix部分来定义需要测试的多维度组合。一个典型的维度是MATLAB版本。

pipeline { agent none // 在顶层不指定，在stage内通过matrix指定 stages { stage('Build and Test Across MATLAB Versions') { matrix { agent { label "${MATLAB_VERSION}-${PLATFORM}" // 例如 'R2023b-windows' 或 'R2021a-linux' } axes { axis { name 'MATLAB_VERSION' values 'R2023b', 'R2021a' } axis { name 'PLATFORM' values 'windows', 'linux' } } stages { // 每个组合内执行的stage } } } } }

这个矩阵会生成2（版本）x 2（平台）= 4个并行的构建任务。每个任务都会在具有对应标签的代理节点上执行stages内的步骤。

4.2 单个矩阵单元内的执行步骤

在每个矩阵单元（即特定的MATLAB版本和平台）内，我们需要定义具体的构建和测试步骤。

stages { stage('Checkout') { steps { checkout scm // 检出代码 } } stage('Prepare MATLAB Path') { steps { script { // 将项目根目录及其子文件夹添加到MATLAB搜索路径 // 这里生成一个临时启动脚本 def matlabScript = """ addpath(genpath('${WORKSPACE}')); savepath; """ writeFile file: 'startup_for_ci.m', text: matlabScript } } } stage('Run MATLAB Tests') { steps { script { // 根据平台构造不同的MATLAB命令 def matlabCmd if (env.PLATFORM == 'windows') { matlabCmd = "matlab -batch \"run('${WORKSPACE}\\startup_for_ci.m'); runAllTests;\" -logfile ${WORKSPACE}\\matlab_test_log.txt" } else { matlabCmd = "matlab -batch \"run('${WORKSPACE}/startup_for_ci.m'); runAllTests;\" -logfile ${WORKSPACE}/matlab_test_log.txt" } // 执行命令 try { if (env.PLATFORM == 'windows') { bat matlabCmd } else { sh matlabCmd } } catch (Exception e) { echo "MATLAB execution failed. Check the log file." // 可以在这里解析日志，获取更详细的错误信息 currentBuild.result = 'FAILURE' } } } } stage('Archive Results') { steps { // 归档测试日志和可能生成的报告（如PDF、图表） archiveArtifacts artifacts: 'matlab_test_log.txt, **/*.pdf, **/*.png', fingerprint: true } } }

这里的runAllTests是你需要在项目根目录下编写的一个入口函数。例如，runAllTests.m的内容可能如下：

function runAllTests import matlab.unittest.TestSuite; import matlab.unittest.TestRunner; import matlab.unittest.plugins.XMLPlugin; import matlab.unittest.plugins.ToFile; % 创建测试套件：自动发现当前文件夹及子文件夹下所有测试 suite = TestSuite.fromFolder(pwd, 'IncludingSubfolders', true); % 创建测试运行器 runner = TestRunner.withTextOutput; % 添加JUnit格式XML输出插件，便于Jenkins解析 xmlFile = fullfile(getenv('WORKSPACE'), 'test-results.xml'); plugin = XMLPlugin.producingJUnitFormat(xmlFile); runner.addPlugin(plugin); % 运行测试 results = runner.run(suite); % 根据测试结果决定退出码（非必须，-batch模式下MATLAB会处理异常） if any([results.Failed]) disp('Some tests failed.'); exit(1); else disp('All tests passed.'); exit(0); end end

4.3 关键技巧与注意事项

1. 路径处理：Windows和Linux的路径分隔符（\vs/）和命令解释器（batvssh）不同，在Jenkinsfile中必须用env.PLATFORM进行判断。使用${WORKSPACE}这个Jenkins环境变量来获取当前任务的工作目录绝对路径。
2. 资源清理：MATLAB在运行过程中可能会产生临时文件。在Pipeline开头或结尾，使用cleanWs()指令（需要Workspace Cleanup插件）或手动删除命令来清理工作空间，避免磁盘空间被占满。
3. 超时控制：有些测试可能陷入死循环。使用timeout步骤包装你的MATLAB执行命令。

   stage('Run MATLAB Tests') { steps { timeout(time: 30, unit: 'MINUTES') { script { // ... 执行matlabCmd的代码 } } } }

4. 许可证检查：可以在Pipeline最开始添加一个阶段，执行一个简单的MATLAB命令（如matlab -batch "disp('License checked')"）来验证许可证是否可用。如果失败，直接失败构建，避免后续更耗时的步骤。

5. 测试结果集成与报告

仅仅运行测试是不够的，我们需要让Jenkins理解测试结果，并以直观的形式展示出来。

5.1 解析JUnit格式报告

在上面的runAllTests.m示例中，我们使用了XMLPlugin.producingJUnitFormat来生成一个JUnit风格的XML报告。这是CI工具界的通用格式。在Jenkins中，你需要安装JUnit Plugin。

在Pipeline脚本的最后，或者在一个单独的post阶段，添加结果收集步骤：

post { always { // 无论构建成功失败，都尝试收集测试报告 junit '**/test-results.xml' // 也可以归档日志 archiveArtifacts artifacts: '**/matlab_test_log.txt', allowEmptyArchive: true } }

这样，每次构建后，Jenkins的界面中就会出现“Test Result”趋势图，点击可以查看每个测试用例的通过/失败详情、执行时间等，非常方便。

5.2 自定义HTML报告

如果MATLAB测试生成了更丰富的HTML报告（例如使用matlab.unittest.plugins.TestReportPlugin），你可以将其归档，并通过Jenkins的HTML Publisher插件进行展示。

1. 在runAllTests.m中添加生成HTML报告的插件。
2. 在Jenkinsfile的post阶段归档HTML文件。
3. 安装HTML Publisher Plugin。
4. 在Pipeline脚本中配置发布：

   publishHTML(target: [ reportName: 'MATLAB Test Report', reportDir: 'html_report_folder', // 报告生成的目录 reportFiles: 'index.html', keepAll: true, alwaysLinkToLastBuild: true ])

5.3 通知机制

构建失败或恢复成功时，及时通知相关人员。使用Email Extension Plugin可以高度定制邮件内容。

post { failure { emailext ( subject: "构建失败: ${env.JOB_NAME} - ${env.BUILD_NUMBER} (${env.MATLAB_VERSION} on ${env.PLATFORM})", body: "请检查构建日志：${env.BUILD_URL}", to: 'team@example.com' ) } fixed { emailext ( subject: "构建恢复: ${env.JOB_NAME} - ${env.BUILD_NUMBER}", body: "之前失败的构建已恢复成功。", to: 'team@example.com' ) } }

6. 高级话题与实战避坑指南

在实际搭建和运行过程中，你会遇到比基础教程更复杂的情况。以下是我从多个项目中总结出的经验。

6.1 处理图形化依赖

很多MATLAB代码会隐式地调用图形功能，例如figure,plot,imshow。在无图形界面的CI服务器上，这会导致错误。

• 解决方案：在启动MATLAB时，使用-nodisplay和-nosplash参数。对于需要图形功能但不需要显示的情况，可以使用软件OpenGL渲染。
  • Linux：确保安装了libgl1-mesa-dri等包，并设置环境变量export MATLAB_USE_SOFTWARE_OPENGL=1。
  • Windows：通常问题较少，但确保系统有基本的图形驱动。
• 更彻底的方案：重构代码，将计算和绘图分离。CI只运行计算和断言部分，绘图代码可以跳过，或者使用-nodisplay模式，图形会被丢弃但代码不会报错。可以使用isdeployed或检查环境变量（如CI）来判断是否在CI环境中，从而跳过图形操作。

6.2 管理工具箱依赖

你的项目可能依赖特定的工具箱。在构建矩阵中，你需要确保对应节点安装了这些工具箱。

• 在静默安装文件installer_input.txt中精确指定产品列表。为不同项目维护不同的产品列表文件。
• 在Pipeline中增加验证步骤：在运行测试前，先执行一个MATLAB命令来验证所需工具箱是否存在。

  % check_toolboxes.m required_toolboxes = {'Signal Processing Toolbox', 'Image Processing Toolbox'}; v = ver; installed_toolboxes = {v.Name}; for i = 1:length(required_toolboxes) if ~any(strcmp(installed_toolboxes, required_toolboxes{i})) error('缺失必要工具箱: %s', required_toolboxes{i}); end end disp('所有必要工具箱已安装。');

6.3 性能优化与构建缓存

MATLAB启动本身有一定开销，对于大量小型测试，频繁启动会浪费很多时间。

• 批处理测试：尽量将多个测试脚本的调用写在一个-batch命令中，减少MATLAB的启动次数。这就是为什么我们推荐一个runAllTests.m入口函数。
• 使用并行计算工具箱：如果你的测试是独立的，可以在runAllTests.m中使用parfor或parfeval来并行运行测试套件，充分利用CI节点的多核性能。但要注意管理好并行池的生命周期。
• 缓存依赖项：如果项目使用了第三方MATLAB函数或库（如FileExchange下载的），可以考虑在构建节点上将其安装在固定位置，而不是每次构建都重新下载。可以使用Jenkins的“自定义工具”功能来管理这些依赖。

6.4 与模型化设计（Simulink）集成

如果你的项目包含Simulink模型，自动化测试会更加复杂，但原则相通。

• 使用sim命令进行模型仿真：可以在MATLAB脚本中编写仿真和验证逻辑。
• 使用Simulink Test模块：这是更专业的方式。你可以创建测试用例，并通过stm.run命令在无头模式下执行。测试结果同样可以导出为JUnit格式。
• 模型编译：首次仿真会有编译时间。可以考虑在CI中缓存编译产物（如.slxc文件），但需要小心处理模型版本和依赖关系的同步。

6.5 常见错误与排查

1. 错误：matlab: command not found

   • 原因：PATH环境变量未正确设置，或者Jenkins服务账户的环境变量与交互式Shell不同。
   • 排查：在Pipeline中增加一个sh 'echo $PATH'或bat 'echo %PATH%'的步骤，检查路径。最稳妥的方法是在Pipeline中使用MATLAB的绝对路径，如/usr/local/MATLAB/R2023b/bin/matlab。

2. 错误：License checkout failed

   • 原因：许可证服务器不可达、许可证数量不足、或服务账户无权限。
   • 排查：首先在构建节点上，切换到Jenkins服务账户（如sudo -u jenkins -i），手动执行MATLAB命令看是否成功。检查防火墙设置，确保可以访问许可证服务器的端口（通常是27000）。查看MATLAB的许可证日志文件。

3. 错误：测试通过，但JUnit报告未被发现

   • 原因：XML报告文件的路径不匹配，或者报告格式不符合JUnit标准。
   • 排查：确认junit步骤中指定的文件路径模式能匹配到生成的文件。检查生成的XML文件内容，确保其是有效的JUnit XML格式。MATLAB Unit Test插件生成的格式通常是兼容的。

4. 错误：构建成功，但MATLAB脚本中的assert失败并未导致构建失败

   • 原因：MATLAB脚本中的错误或断言失败可能被try-catch块捕获并处理，而未以非零退出码结束。
   • 解决方案：确保在测试脚本的顶层，任何失败都能导致exit(1)。使用-batch参数时，MATLAB脚本中任何未捕获的错误都会导致MATLAB以非零码退出，从而让Jenkins感知到失败。因此，要避免在顶层使用try-catch来吞掉所有错误。

搭建这样一个“构建矩阵实验室”初期确实需要一些投入，但一旦运转起来，它带来的收益是巨大的：每一次代码提交，你都能立刻知道它在多个关键环境下的兼容性状态，再也不用担心“在我机器上是好的”这种问题。它迫使你将MATLAB代码当作真正的工程代码来对待，编写可测试、可复现的模块，这本身就会极大地提升代码质量。从手动点击运行到自动化验证，这不仅是效率的提升，更是工作范式的转变。