3. MATLAB项目入口与启动脚本标准化

一个可交付的MATLAB工程，最忌讳的是“每个人打开不同的脚本开始跑”。当项目从个人脚本演变为团队交付物时，必须有一个唯一入口，让任何人、任何机器、任何运行模式都从同一个起点进入。这个入口就是 main.m。它的职责不是完成全部计算，而是把“启动”这件事标准化：初始化环境、检查依赖、加载参数、决定运行模式，然后把控制权交给真正的业务函数。

为什么必须统一入口

没有统一入口时，常见问题包括：路径依赖当前工作目录、临时变量污染工作区、参数散落在多个脚本中、调试模式与批处理模式行为不一致、交付后对方不知道先运行哪个文件。统一入口的价值在于把“不确定性”收敛到一个文件里。交付方只需说明“运行 main”，接收方无需理解内部结构即可启动；同时，入口文件本身成为环境契约的声明处，任何缺失的工具箱、数据文件或配置项都会在启动阶段被明确暴露，而不是在计算中途报出难以定位的错误。

main.m 的推荐结构

一个标准化的 main.m 通常按固定顺序完成五件事：确定项目根目录、初始化环境、检查运行环境、加载参数、按运行模式分发。下面给出一个可直接参考的骨架，示例参数均为教学假设值。

function main(mode, varargin)
% MAIN 项目统一入口
% 用法:
%   main()                  % 默认交互运行
%   main('batch')           % 批处理运行
%   main('test')            % 自检模式
%   main('batch','cfg','cfg_prod.m')

    if nargin < 1 || isempty(mode)
        mode = 'interactive';
    end

    % 1. 定位项目根目录（以本文件位置为基准）
    rootDir = fileparts(mfilename('fullpath'));
    addpath(genpath(fullfile(rootDir,'src')));
    addpath(fullfile(rootDir,'config'));

    % 2. 环境初始化
    close all; clc;
    restoredefaultpath;                 % 清空历史路径污染
    addpath(genpath(fullfile(rootDir,'src')));

    % 3. 环境检查
    envReport = checkEnvironment(rootDir);
    if ~envReport.passed
        error('环境检查未通过: %s', strjoin(envReport.failed, ', '));
    end

    % 4. 参数加载
    cfgFile = 'cfg_default.m';
    idx = find(strcmp(varargin,'cfg'),1);
    if ~isempty(idx), cfgFile = varargin{idx+1}; end
    cfg = loadConfig(fullfile(rootDir,'config',cfgFile));

    % 5. 运行模式分发
    switch lower(mode)
        case 'interactive'
            runInteractive(cfg);
        case 'batch'
            runBatch(cfg);
        case 'test'
            runSelfTest(cfg);
        otherwise
            error('未知运行模式: %s', mode);
    end
end

这段骨架的关键设计点有三处。第一，用 mfilename('fullpath') 而不是 pwd 定位根目录，保证无论从哪个目录调用都能找到项目资源。第二，restoredefaultpath 后重新添加项目路径，避免上一次运行残留的路径影响本次结果，这对可复现性至关重要。第三，模式通过参数传入而非修改代码，使同一份代码可以在交互、批处理和自检之间切换。

启动初始化与环境检查

初始化阶段应完成三件事：清理工作区状态、设置随机种子、配置日志与输出目录。随机种子尤其重要，若项目涉及随机采样或蒙特卡洛，固定种子是结果可复现的前提。环境检查则回答“这台机器能不能跑”：MATLAB版本是否满足最低要求、必需工具箱是否安装、输入数据文件是否存在、输出目录是否可写。检查结果应汇总为一个结构体，而不是遇到第一个问题就中断，这样使用者能一次性看到全部缺失项。

function r = checkEnvironment(rootDir)
    r.passed = true; r.failed = {};
    needVer = 'R2021b';
    if verLessThan('matlab', needVer)
        r.passed = false; r.failed{end+1} = ['MATLAB<' needVer];
    end
    needTbx = {'Statistics and Machine Learning Toolbox', ...
               'Parallel Computing Toolbox'};
    for k = 1:numel(needTbx)
        if isempty(ver(needTbx{k}))
            r.passed = false; r.failed{end+1} = needTbx{k};
        end
    end
    dataFile = fullfile(rootDir,'data','input.mat');
    if ~isfile(dataFile)
        r.passed = false; r.failed{end+1} = 'data/input.mat';
    end
end

参数加载与运行模式切换

参数加载推荐使用“默认配置 + 覆盖”的方式：cfg_default.m 定义全部字段的默认值，生产或测试配置只覆盖需要变化的字段。这样新增参数时只需改默认文件，不会破坏已有配置。运行模式则决定入口之后的行为：交互模式保留图形窗口、便于逐步观察；批处理模式关闭图形、把结果写入文件并返回退出码，适合自动化流水线；自检模式用少量数据快速验证环境与主流程是否连通，通常在交付前运行一次。

交付前的自检与常见问题

入口标准化后，交付前应至少运行一次 main('test')，确认环境检查通过、参数能正确加载、主流程能跑通最小数据集。常见问题有三类：一是路径问题，表现为“在我机器上能跑”，根因是使用了 pwd 或硬编码绝对路径，应统一改为基于 mfilename 的相对定位；二是模式耦合，表现为批处理模式下仍弹出图形窗口导致流水线挂起，应在批处理分支显式设置 set(0,'DefaultFigureVisible','off')；三是参数静默失败，表现为配置字段拼写错误但程序继续用默认值运行，应在加载后校验必需字段是否存在，缺失即报错。

把入口做标准化，本质上是把“怎么启动”从口头约定变成代码契约。当 main.m 稳定承担起初始化、检查、加载与分发四项职责后，项目内部的业务函数就可以专注于计算本身，交付质量也随之从“能跑”提升到“可复现、可交接、可自动化”。