1. 项目概述当“矩阵实验室”遇上“构建矩阵”看到这个标题你可能会心一笑。没错这玩的是一个经典的双关梗。一方面它指向了那个在科学计算和工程领域如雷贯耳的名字——MATLABMatrix 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提供了几种方式命令行启动与-batch选项这是最核心的方式。通过命令matlab -batch yourScriptMATLAB会启动、执行脚本中的命令然后自动退出。这是CI流水线的基石。MATLAB运行时MCR与编译器如果你最终需要交付的是独立应用程序或库MATLAB Compiler可以将你的代码打包并依赖免费的MATLAB Runtime来执行。这在CI中可以用来构建和测试打包后的产物。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中你会大量使用ShellLinux或Batch/PowerShellWindows来调用MATLAB命令。对于复杂的逻辑也可以用Python来编写预处理或结果解析脚本。依赖管理可选但推荐对于大型项目可以考虑使用MATLAB自带的“项目管理”功能或第三方工具来管理工具箱依赖但这在CI中通常通过确保构建节点安装了正确的工具箱版本来解决。3. 构建环境准备与MATLAB配置这一节是实操的起点也是最容易踩坑的地方。我们的目标是在一台或多台机器上为Jenkins准备好可以自动化执行MATLAB命令的环境。3.1 Jenkins节点的MATLAB安装假设我们使用Jenkins的“主从”架构将构建任务分发到安装了MATLAB的“代理节点”上执行。静默安装MATLAB在CI节点上我们通常不希望进行交互式安装。MathWorks提供了静默安装方式。你需要准备一个installer_input.txt文件其中包含安装路径、产品列表如MATLAB, Simulink, 特定工具箱、许可证文件路径等信息。然后通过安装程序配合-inputFile参数进行安装。这对于通过Docker镜像或系统镜像快速部署构建节点至关重要。# 示例命令Linux ./install -inputFile /path/to/installer_input.txt -mode silent许可证配置这是核心挑战。CI服务器需要能够自动获取MATLAB许可证。网络许可证最常见的方式。在节点上配置LM_LICENSE_FILE或MLM_LICENSE_FILE环境变量指向公司的许可证服务器。确保Jenkins服务运行的用户有权限访问该服务器。文件许可证可以将许可证文件放置在节点固定位置并在安装时指定。但需注意许可证的绑定机制。重要提示务必测试在Jenkins服务账户如jenkins用户下能否成功通过命令行启动MATLAB并获取许可。最好写一个简单的测试脚本放入CI流程的第一步。环境变量与PATH确保MATLAB的可执行文件路径例如C:\Program Files\MATLAB\R2023b\bin或/usr/local/MATLAB/R2023b/bin被添加到系统的PATH环境变量中。这样在Jenkins的Pipeline脚本中才能直接使用matlab命令。3.2 创建Jenkins Pipeline项目在Jenkins中我们选择使用“Pipeline”项目类型因为它将构建流程以代码Jenkinsfile的形式定义易于版本控制和复用。新建Item选择“Pipeline”给它起个名字比如matlab-matrix-build。Pipeline定义选择“Pipeline script from SCM”。将你的Git仓库地址填入并指定Jenkinsfile的路径默认为根目录下的Jenkinsfile。这意味着你的构建逻辑将和源代码一起管理。配置代理节点在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 end4.3 关键技巧与注意事项路径处理Windows和Linux的路径分隔符\vs/和命令解释器batvssh不同在Jenkinsfile中必须用env.PLATFORM进行判断。使用${WORKSPACE}这个Jenkins环境变量来获取当前任务的工作目录绝对路径。资源清理MATLAB在运行过程中可能会产生临时文件。在Pipeline开头或结尾使用cleanWs()指令需要Workspace Cleanup插件或手动删除命令来清理工作空间避免磁盘空间被占满。超时控制有些测试可能陷入死循环。使用timeout步骤包装你的MATLAB执行命令。stage(Run MATLAB Tests) { steps { timeout(time: 30, unit: MINUTES) { script { // ... 执行matlabCmd的代码 } } } }许可证检查可以在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插件进行展示。在runAllTests.m中添加生成HTML报告的插件。在Jenkinsfile的post阶段归档HTML文件。安装HTML Publisher Plugin。在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: teamexample.com ) } fixed { emailext ( subject: 构建恢复: ${env.JOB_NAME} - ${env.BUILD_NUMBER}, body: 之前失败的构建已恢复成功。, to: teamexample.com ) } }6. 高级话题与实战避坑指南在实际搭建和运行过程中你会遇到比基础教程更复杂的情况。以下是我从多个项目中总结出的经验。6.1 处理图形化依赖很多MATLAB代码会隐式地调用图形功能例如figure,plot,imshow。在无图形界面的CI服务器上这会导致错误。解决方案在启动MATLAB时使用-nodisplay和-nosplash参数。对于需要图形功能但不需要显示的情况可以使用软件OpenGL渲染。Linux确保安装了libgl1-mesa-dri等包并设置环境变量export MATLAB_USE_SOFTWARE_OPENGL1。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 常见错误与排查错误matlab: command not found原因PATH环境变量未正确设置或者Jenkins服务账户的环境变量与交互式Shell不同。排查在Pipeline中增加一个sh echo $PATH或bat echo %PATH%的步骤检查路径。最稳妥的方法是在Pipeline中使用MATLAB的绝对路径如/usr/local/MATLAB/R2023b/bin/matlab。错误License checkout failed原因许可证服务器不可达、许可证数量不足、或服务账户无权限。排查首先在构建节点上切换到Jenkins服务账户如sudo -u jenkins -i手动执行MATLAB命令看是否成功。检查防火墙设置确保可以访问许可证服务器的端口通常是27000。查看MATLAB的许可证日志文件。错误测试通过但JUnit报告未被发现原因XML报告文件的路径不匹配或者报告格式不符合JUnit标准。排查确认junit步骤中指定的文件路径模式能匹配到生成的文件。检查生成的XML文件内容确保其是有效的JUnit XML格式。MATLAB Unit Test插件生成的格式通常是兼容的。错误构建成功但MATLAB脚本中的assert失败并未导致构建失败原因MATLAB脚本中的错误或断言失败可能被try-catch块捕获并处理而未以非零退出码结束。解决方案确保在测试脚本的顶层任何失败都能导致exit(1)。使用-batch参数时MATLAB脚本中任何未捕获的错误都会导致MATLAB以非零码退出从而让Jenkins感知到失败。因此要避免在顶层使用try-catch来吞掉所有错误。搭建这样一个“构建矩阵实验室”初期确实需要一些投入但一旦运转起来它带来的收益是巨大的每一次代码提交你都能立刻知道它在多个关键环境下的兼容性状态再也不用担心“在我机器上是好的”这种问题。它迫使你将MATLAB代码当作真正的工程代码来对待编写可测试、可复现的模块这本身就会极大地提升代码质量。从手动点击运行到自动化验证这不仅是效率的提升更是工作范式的转变。
MATLAB自动化测试：基于Jenkins构建矩阵的CI/CD实践指南
发布时间：2026/6/24 20:37:18
1. 项目概述当“矩阵实验室”遇上“构建矩阵”看到这个标题你可能会心一笑。没错这玩的是一个经典的双关梗。一方面它指向了那个在科学计算和工程领域如雷贯耳的名字——MATLABMatrix 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提供了几种方式命令行启动与-batch选项这是最核心的方式。通过命令matlab -batch yourScriptMATLAB会启动、执行脚本中的命令然后自动退出。这是CI流水线的基石。MATLAB运行时MCR与编译器如果你最终需要交付的是独立应用程序或库MATLAB Compiler可以将你的代码打包并依赖免费的MATLAB Runtime来执行。这在CI中可以用来构建和测试打包后的产物。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中你会大量使用ShellLinux或Batch/PowerShellWindows来调用MATLAB命令。对于复杂的逻辑也可以用Python来编写预处理或结果解析脚本。依赖管理可选但推荐对于大型项目可以考虑使用MATLAB自带的“项目管理”功能或第三方工具来管理工具箱依赖但这在CI中通常通过确保构建节点安装了正确的工具箱版本来解决。3. 构建环境准备与MATLAB配置这一节是实操的起点也是最容易踩坑的地方。我们的目标是在一台或多台机器上为Jenkins准备好可以自动化执行MATLAB命令的环境。3.1 Jenkins节点的MATLAB安装假设我们使用Jenkins的“主从”架构将构建任务分发到安装了MATLAB的“代理节点”上执行。静默安装MATLAB在CI节点上我们通常不希望进行交互式安装。MathWorks提供了静默安装方式。你需要准备一个installer_input.txt文件其中包含安装路径、产品列表如MATLAB, Simulink, 特定工具箱、许可证文件路径等信息。然后通过安装程序配合-inputFile参数进行安装。这对于通过Docker镜像或系统镜像快速部署构建节点至关重要。# 示例命令Linux ./install -inputFile /path/to/installer_input.txt -mode silent许可证配置这是核心挑战。CI服务器需要能够自动获取MATLAB许可证。网络许可证最常见的方式。在节点上配置LM_LICENSE_FILE或MLM_LICENSE_FILE环境变量指向公司的许可证服务器。确保Jenkins服务运行的用户有权限访问该服务器。文件许可证可以将许可证文件放置在节点固定位置并在安装时指定。但需注意许可证的绑定机制。重要提示务必测试在Jenkins服务账户如jenkins用户下能否成功通过命令行启动MATLAB并获取许可。最好写一个简单的测试脚本放入CI流程的第一步。环境变量与PATH确保MATLAB的可执行文件路径例如C:\Program Files\MATLAB\R2023b\bin或/usr/local/MATLAB/R2023b/bin被添加到系统的PATH环境变量中。这样在Jenkins的Pipeline脚本中才能直接使用matlab命令。3.2 创建Jenkins Pipeline项目在Jenkins中我们选择使用“Pipeline”项目类型因为它将构建流程以代码Jenkinsfile的形式定义易于版本控制和复用。新建Item选择“Pipeline”给它起个名字比如matlab-matrix-build。Pipeline定义选择“Pipeline script from SCM”。将你的Git仓库地址填入并指定Jenkinsfile的路径默认为根目录下的Jenkinsfile。这意味着你的构建逻辑将和源代码一起管理。配置代理节点在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 end4.3 关键技巧与注意事项路径处理Windows和Linux的路径分隔符\vs/和命令解释器batvssh不同在Jenkinsfile中必须用env.PLATFORM进行判断。使用${WORKSPACE}这个Jenkins环境变量来获取当前任务的工作目录绝对路径。资源清理MATLAB在运行过程中可能会产生临时文件。在Pipeline开头或结尾使用cleanWs()指令需要Workspace Cleanup插件或手动删除命令来清理工作空间避免磁盘空间被占满。超时控制有些测试可能陷入死循环。使用timeout步骤包装你的MATLAB执行命令。stage(Run MATLAB Tests) { steps { timeout(time: 30, unit: MINUTES) { script { // ... 执行matlabCmd的代码 } } } }许可证检查可以在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插件进行展示。在runAllTests.m中添加生成HTML报告的插件。在Jenkinsfile的post阶段归档HTML文件。安装HTML Publisher Plugin。在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: teamexample.com ) } fixed { emailext ( subject: 构建恢复: ${env.JOB_NAME} - ${env.BUILD_NUMBER}, body: 之前失败的构建已恢复成功。, to: teamexample.com ) } }6. 高级话题与实战避坑指南在实际搭建和运行过程中你会遇到比基础教程更复杂的情况。以下是我从多个项目中总结出的经验。6.1 处理图形化依赖很多MATLAB代码会隐式地调用图形功能例如figure,plot,imshow。在无图形界面的CI服务器上这会导致错误。解决方案在启动MATLAB时使用-nodisplay和-nosplash参数。对于需要图形功能但不需要显示的情况可以使用软件OpenGL渲染。Linux确保安装了libgl1-mesa-dri等包并设置环境变量export MATLAB_USE_SOFTWARE_OPENGL1。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 常见错误与排查错误matlab: command not found原因PATH环境变量未正确设置或者Jenkins服务账户的环境变量与交互式Shell不同。排查在Pipeline中增加一个sh echo $PATH或bat echo %PATH%的步骤检查路径。最稳妥的方法是在Pipeline中使用MATLAB的绝对路径如/usr/local/MATLAB/R2023b/bin/matlab。错误License checkout failed原因许可证服务器不可达、许可证数量不足、或服务账户无权限。排查首先在构建节点上切换到Jenkins服务账户如sudo -u jenkins -i手动执行MATLAB命令看是否成功。检查防火墙设置确保可以访问许可证服务器的端口通常是27000。查看MATLAB的许可证日志文件。错误测试通过但JUnit报告未被发现原因XML报告文件的路径不匹配或者报告格式不符合JUnit标准。排查确认junit步骤中指定的文件路径模式能匹配到生成的文件。检查生成的XML文件内容确保其是有效的JUnit XML格式。MATLAB Unit Test插件生成的格式通常是兼容的。错误构建成功但MATLAB脚本中的assert失败并未导致构建失败原因MATLAB脚本中的错误或断言失败可能被try-catch块捕获并处理而未以非零退出码结束。解决方案确保在测试脚本的顶层任何失败都能导致exit(1)。使用-batch参数时MATLAB脚本中任何未捕获的错误都会导致MATLAB以非零码退出从而让Jenkins感知到失败。因此要避免在顶层使用try-catch来吞掉所有错误。搭建这样一个“构建矩阵实验室”初期确实需要一些投入但一旦运转起来它带来的收益是巨大的每一次代码提交你都能立刻知道它在多个关键环境下的兼容性状态再也不用担心“在我机器上是好的”这种问题。它迫使你将MATLAB代码当作真正的工程代码来对待编写可测试、可复现的模块这本身就会极大地提升代码质量。从手动点击运行到自动化验证这不仅是效率的提升更是工作范式的转变。
