matlab-modernize-code

代码现代化

将已移除或不建议使用的 MATLAB 函数和反模式替换为现代等效方案。此技能负责解决问题，而 MCP 工具 check_matlab_code（MATLAB 的 Code Analyzer）负责检测。

此技能中使用的术语：

• 已移除 — 此函数已不属于 MATLAB；调用会报错。
• 不建议使用 — 此函数仍可运行，但已有更好的 API。它在未来版本中是否会被移除尚不确定。

何时使用

• check_matlab_code 报告生命周期诊断 — 以下三种措辞中的任意一种（不区分大小写；STRMATCH is not recommended 与小写形式表示相同信号）：
  • 'X' is not recommended...（严重性：info）
  • 'X' will be removed in a future release...（严重性：warning）
  • 'X' has been removed...（严重性：error — 代码目前会报错）
• 代码使用了 Code Analyzer 不会标记的不建议使用模式 — 例如 containers.Map、bsxfun、str2num、eval、clear all — 请扫描源代码，而不只是查看诊断信息（参见约定）
• 用户要求将旧 MATLAB 代码现代化、迁移或更新
• 代码使用了下方快速参考表中列出的函数
• 静态分析发现使用了已移除或不建议使用的 API
• 在已知存在已移除或不建议使用模式的领域编写新代码

何时不使用

此技能会将已移除或不建议使用的 API 替换为现代等效方案，但不会：

• 全面审查代码质量
• 调试运行时行为（已移除函数导致的错误除外 — 这类问题属于现代化修复）
• 优化已经正确的代码以提升速度 → 转交给 matlab-optimize-performance
• 编写或迁移函数输入/输出验证（arguments 块、inputParser/validateattributes → mustBe* 验证器、重复参数、名称-值转发）→ 转交给 matlab-validate-function-arguments

快速参考：已移除、不建议使用的函数及反模式

主题	建议	起始版本	类别	原因
csvread / dlmread	readmatrix	R2019a	文件 I/O
csvwrite / dlmwrite	writematrix	R2019a	文件 I/O
xlsread	readtable、readmatrix	R2019a	文件 I/O
xlswrite	writetable、writematrix	R2019a	文件 I/O
datenum / datestr / now	datetime（使用 string/char 格式化）	R2022b	日期/时间（不建议使用）	Code Analyzer 会标记
eval / evalc / evalin	动态字段名 s.(name)、函数句柄 / feval、用于顺序名称的元胞数组	—	反模式	不会编译（速度慢）；可能覆盖工作区变量；难以调试；存在注入风险
str2num	str2num(text, Evaluation="restricted")	R2022a	安全性	不受限制的形式会通过 eval 执行输入（存在注入风险）；参见参考资料
uicontrol	uibutton、uidropdown 等	R2016a	UI/应用
guide	appdesigner	R2025a	UI（已移除）
strmatch	startsWith、matches	R2019b	字符串
clear all	clearvars	—	工作区	会清除内存中的函数；导致强制重新编译

datestr 的细节： datestr 的作用是将日期格式化为文本，因此它的现代替代方案是 string(dt) / char(dt)，或设置 dt.Format，而不是直接调用 datetime(...)。使用 datetime 替代 datenum/now（数值/序列日期路径）。两者都未被移除；自 R2022b 起，Code Analyzer 均将其标记为“不建议使用”。

s = datestr(t, 'yyyy-mm-dd HH:MM:SS');          % 旧
s = string(t, 'yyyy-MM-dd HH:mm:ss');           % 新 — 注意格式说明符有所变化：
                                                % datetime 使用 MM=月、mm=分钟（datestr 中 mm=月、MM=分钟）

现代设计模式

所有新代码中优先使用以下模式：

基于表的工作流

data = readtable('sensors.csv');
data.Timestamp = datetime(data.Timestamp);
data.Status = categorical(data.Status);
recentData = data(data.Timestamp > datetime('today') - days(7), :);
summary = groupsummary(recentData, 'SensorID', 'mean', 'Value');

字符串数组（而非字符数组）

name = "John";                        % not 'John'
names = ["John", "Jane", "Bob"];      % not {'John','Jane','Bob'}
fullName = firstName + " " + lastName; % not [first,' ',last]
idx = contains(names, "Jo");          % not cellfun + strfind

Arguments 块（而非 nargin/varargin）

function result = processData(data, options)
    arguments
        data (:,:) double
        options.Method (1,1) string {mustBeMember(options.Method, ["fast","accurate"])} = "fast"
        options.Verbose (1,1) logical = false
    end
end

关键迁移

文件 I/O：csvread/xlsread → readmatrix/readtable

% Old                          → Modern
M = csvread('data.csv');       % M = readmatrix("data.csv");
M = dlmread('data.txt','\t'); % M = readmatrix("data.txt", Delimiter="\t");
[n,t,r] = xlsread('f.xlsx');  % T = readtable("f.xlsx");
csvwrite('out.csv', M);       % writematrix(M, "out.csv");
xlswrite('out.xlsx', data);   % writetable(T, "out.xlsx");

eval → 结构化替代方案

避免使用 eval/evalc/evalin：文本不会被编译（速度较慢），可能会在不提示的情况下覆盖工作区变量，而且难以阅读和调试。根据意图选择合适的结构 — 完整列表请参阅 references/core-functions-guidance.md（顺序名称、sprintf 文件名、try/catch）。

% Old: eval([varName ' = 42;']);          -> dynamic field name
s.(varName) = 42;

% Old: result = eval(['process_' method '(x)']);  -> handle dispatch table
handlers.fast = @processFast;
handlers.slow = @processSlow;
result = handlers.(method)(x);

% Old: for n=1:10, eval(['A' int2str(n) '=magic(n);']); end  -> index a cell
A = cell(10,1);
for n = 1:10, A{n} = magic(n); end

参考资料

在特定领域工作时加载以下资料：

加载时机……	参考资料
核心 MATLAB 函数（文件 I/O、字符串、UI）；安全反模式（eval/str2num）、containers.Map→dictionary、bsxfun→隐式扩展	references/core-functions-guidance.md
深度学习（trainNetwork→trainnet、LayerGraph/SeriesNetwork/DAGNetwork→dlnetwork、classify、activations）	references/deep-learning-guidance.md
信号处理函数	references/signal-processing-guidance.md
音频/视频 I/O 迁移（wavread、aviread）	references/audio-video-guidance.md
优化工具箱（optimset、optimtool）	references/optimization-guidance.md
控制系统绘图选项	references/control-systems-guidance.md
图像处理 ROI 对象	references/image-processing-guidance.md
统计/机器学习（svmtrain、dataset、classregtree）	references/statistics-ml-guidance.md
Communications System 对象	references/communications-guidance.md
Mapping Toolbox（webmap、wmmarker、wmline、geotiffread、mfwdtran、makerefmat）	references/mapping-guidance.md

约定

• 始终先运行 check_matlab_code — 让静态分析找出已移除或不建议使用的内容
• 运行后，扫描源代码，查找 Code Analyzer 可能未充分提示的模式： str2num（仅作为性能提示提及）；containers.Map（见下一条）。
• check_matlab_code 不会标记 containers.Map。 使用它的普通脚本会返回零条诊断；作为 containers.Map 属性默认值时，只会出现句柄默认值共享警告（“所有实例共享相同的对象数据”）。先检测的工作流不会发现这种迁移 — 应将任何 containers.Map 用法，以及属性上的该句柄共享警告，都视为 containers.Map→dictionary 的迁移触发条件。
• subplot 并未弃用，也不属于不建议使用的内容。 它完全受支持，check_matlab_code 绝不会标记它。tiledlayout/nexttile 是新代码的首选替代方案，而非必须进行的迁移 — 不要建议用户替换仍能正常工作的 subplot 代码。
• 先修复已移除或不建议使用的模式，再处理其他代码质量问题
• 编写新代码时，从一开始就使用现代模式 — 不要先写旧式代码，再稍后修复
• 'X' has been removed 诊断（严重性为 error）表示该函数目前就会报错 — 应将其视为修复性现代化任务，优先级高于“not recommended”（信息）和“will be removed”（警告）情况
• 迁移时，针对旧行为测试现代替代方案，以确认两者等效
• 旧版 .m 文件通常使用 Windows-1252 编码。 编辑后，确认非 ASCII 字符（°、µ、±）仍完好 — 如果差异显示注释或字符串中有一行无关改动，通常是字节被重新编码，而非你的编辑所致。
• 查阅特定领域的参考文件，了解带代码示例的详细迁移模式

---

Copyright 2026 The MathWorks, Inc.

---