📚 课程目录第2章 MATLAB工程化开发环境配置

2. MATLAB工程化开发环境配置

当算法从单文件脚本走向多人协作的工程系统时，环境配置就不再是“装个MATLAB”这么简单。一个可复现的工程环境，核心目标是：任何人拿到代码仓库后，能在自己的机器上以一致的方式启动、运行、测试，而不依赖口头约定或某台特定电脑上的历史配置。本节围绕目录结构、路径管理、启动脚本、依赖管理与团队协作五个方面展开。

一、项目目录结构：用物理布局表达逻辑边界

目录结构是工程环境的骨架。它应当让“代码、数据、配置、测试、文档、产物”各归其位，避免所有文件堆在根目录。一个适用于算法开发与验证的典型结构如下：

myAlgoProject/
├─ startup.m              % 环境入口脚本
├─ project.config.json    % 工程配置（路径、版本、开关）
├─ src/                   % 算法源码
│   ├─ core/              % 核心算法
│   ├─ io/                % 数据读写
│   └─ utils/             % 通用工具函数
├─ test/                  % 单元测试与回归测试
│   ├─ unit/
│   └─ regression/
├─ data/                  % 输入数据（小样本入库，大文件外置）
│   ├─ raw/
│   └─ processed/
├─ config/                % 参数文件、标定表
├─ docs/                  % 设计说明、接口文档
├─ build/                 % 生成代码、编译产物（不入库）
└─ output/                % 运行结果、日志（不入库）

关键原则有三点：第一，源码与产物分离，build 和 output 应加入 .gitignore，避免仓库膨胀；第二，数据分级，小样本随仓库走，大文件通过外部路径或数据管理工具引用；第三，测试与源码平级，让测试成为一等公民，而不是临时脚本。

二、路径管理：不依赖“当前文件夹”

MATLAB 的搜索路径机制决定了函数能否被找到。工程化环境必须避免依赖“用户手动 cd 到某目录”或“把路径写死在脚本里”。推荐做法是：所有路径都相对于项目根目录解析，并在启动时统一加入搜索路径。

例如，在 startup.m 中通过 mfilename 定位自身位置，反推项目根目录：

rootDir = fileparts(mfilename('fullpath'));
addpath(genpath(fullfile(rootDir,'src')));
addpath(genpath(fullfile(rootDir,'test')));
addpath(fullfile(rootDir,'config'));

这里使用 genpath 递归添加 src 与 test，但要注意：genpath 会把隐藏目录、.git 等也纳入，必要时需过滤。更稳妥的方式是维护一个显式路径清单，或使用 addpath 配合自定义过滤函数。路径管理的验收标准是：在任意工作目录下执行 startup，随后直接调用核心函数不报“未定义函数”错误。

三、启动脚本：环境初始化的唯一入口

startup.m 是团队协作的“契约”。它应当完成：路径添加、配置加载、版本检查、必要变量初始化、随机种子设定。一个可参考的启动脚本结构如下：

function startup()
rootDir = fileparts(mfilename('fullpath'));
addpath(genpath(fullfile(rootDir,'src')));
addpath(genpath(fullfile(rootDir,'test')));

% 加载工程配置
cfgFile = fullfile(rootDir,'project.config.json');
if isfile(cfgFile)
    cfg = jsondecode(fileread(cfgFile));
    assignin('base','CFG',cfg);
end

% 版本与工具箱检查
assert(~verLessThan('matlab','9.10'), '需要 R2021a 及以上版本');
assert(license('test','Signal_Toolbox'), '缺少 Signal Toolbox');

% 固定随机种子，保证可复现
rng(20240101,'twister');
fprintf('[startup] 工程环境就绪，根目录：%s\n', rootDir);
end

注意：启动脚本不应执行耗时计算或修改用户全局状态。它的职责是“把环境摆好”，而不是“跑一遍算法”。

四、依赖管理：显式声明，而非隐式假设

算法工程常见的依赖包括：MATLAB 版本、工具箱、第三方函数库、MEX 编译环境、外部数据文件。团队协作中，依赖必须显式声明并可检查。推荐在 project.config.json 中记录：

{
  "matlabVersion": "R2021a",
  "toolboxes": ["Signal_Toolbox","Statistics_Toolbox"],
  "thirdParty": [
    {"name":"jsonlab","path":"extern/jsonlab","version":"2.0"}
  ],
  "dataRoot": "D:/algoData"
}

启动脚本读取该配置后逐项校验，缺失时给出明确提示，而不是等到运行中途才报错。对于第三方库，建议以子模块或固定版本目录形式纳入仓库，避免“我本地能用”的漂移问题。

五、团队协作环境搭建：从“能跑”到“可复现”

团队协作的关键是消除环境差异。建议约定：统一 MATLAB 版本区间；统一启动方式（先运行 startup）；统一代码风格（如使用 MATLAB 的 code analyzer 配置）；统一测试入口（如 runtests('test')）。此外，应把 startup.m、project.config.json、.gitignore 纳入版本控制，而把 output、build、本地数据目录排除。

下面这张图概括了工程环境各组成部分之间的依赖与调用关系：启动脚本作为入口，读取配置、校验依赖、添加路径，最终支撑源码、测试与数据三块工作区。

最后给出一个可直接使用的环境检查清单，供团队在搭建或交接时逐项确认：

检查项	预期结果	常见问题
MATLAB 版本	≥ R2021a	低版本缺少新函数
工具箱许可	Signal / Statistics 可用	license 未激活
startup 执行	无报错，打印根目录	路径含中文或空格
核心函数调用	直接调用成功	未 addpath 或 genpath 遗漏
测试入口	runtests('test') 可运行	测试依赖数据缺失
随机种子	两次运行结果一致	未固定 rng

环境配置的价值不在于“配置本身”，而在于它把不确定性从每次运行中剥离出去。当目录、路径、启动、依赖四者都被显式管理后，团队才能把精力集中在算法本身，而不是反复排查“为什么你那里能跑、我这里不行”。