matlab-exclude-files

matlab-exclude-files — 忽略文件生成器

分析 MATLAB 工具箱文件夹，并建议从打包内容中排除哪些文件。只建议排除实际存在的文件，不使用通用模板或样板内容。

适用场景

• 用户要求创建忽略文件或从打包内容中排除文件
• 用户询问“哪些内容不应该打包？”或“清理我的打包内容”
• 不存在忽略文件时，在运行 matlab-build-toolbox 之前
• matlab-assess-toolbox 标记出打包问题之后（检查项 16）

不适用场景

• 用户想从 MATLAB 项目中排除文件（而不是从软件包中排除）——使用项目设置
• 用户想定义工具箱范围或公共 API——使用 matlab-define-toolbox-api
• toolbox.ignore 已完整覆盖项目——此技能会报告“没有其他需要排除的内容”

输入

• toolbox_folder：工具箱内容文件夹的路径（默认：toolbox/ 或当前目录）

规则

• 获准前只读：未经用户明确同意，绝不写入文件。
• 仅基于证据：只建议扫描中实际存在的文件所对应的模式。如果匹配的文件或文件夹不存在，绝不提及或包含该模式——即使是作为“通常会排除的内容”或“你也可以考虑排除”。如果没有发现需要排除的内容，请如实说明并停止。
• 不重复：如果 toolbox.ignore 或 package.ignore 已存在，只建议添加尚未覆盖的内容。
• 遵循 MATLAB 默认规则：绝不建议使用 MATLAB 已自动排除的模式：.git/、.svn/、.buildtool/、*.asv、resources/project/、*.prj。这些内容不得出现在建议中或生成的忽略文件中。
• 引用证据：每条建议都应指出找到的具体文件。

可检测的模式

仅在扫描中找到匹配文件时，才建议使用以下模式：

模式	排除原因	影响
*.DS_Store	操作系统元数据，对用户无用	HIGH
Thumbs.db	Windows 缩略图缓存	HIGH
.vscode/	VS Code 设置	HIGH
.idea/	JetBrains IDE 设置	HIGH
*.log	开发/测试运行产生的日志文件	HIGH
*.orig	合并冲突残留文件	HIGH
slprj/	Simulink 项目缓存	HIGH
codegen/	MATLAB Coder 生成的输出	HIGH
*.mltbx	之前构建的软件包	HIGH
tmp/、temp/	临时目录	HIGH
tests/、test/	测试文件（位于工具箱文件夹内时）	MEDIUM
buildUtilities/	构建脚本	MEDIUM
buildfile.m	构建自动化文件（位于工具箱文件夹内时）	MEDIUM
*.cpp、*.c、*.h	MEX 源文件（存在已编译的 .mex* 二进制文件时）	MEDIUM
doc/internal/	面向内部、不供最终用户使用的文档	MEDIUM
CHANGELOG.md、CONTRIBUTING.md	面向开发者的文档	MEDIUM
测试目录中的 *.mat	测试固定数据	MEDIUM
存在同名 .p 文件的 .m 文件	与 pcode 并存的源代码——排除可保护知识产权，但会导致无法使用 help，除非生成 pcode 时保留了帮助内容	MEDIUM

工作流

步骤 1 — 扫描

递归遍历工具箱文件夹。收集所有文件路径和文件夹名称。

步骤 2 — 检查现有文件

在文件夹中查找 toolbox.ignore 或 package.ignore。如果存在，则读取并记录已覆盖的模式。

步骤 3 — 检测

针对扫描中找到的每个文件，检查它是否匹配上表中的已知可忽略模式。只报告实际存在的文件所匹配的模式。对于 pcode 文件对，检查 .p 文件所在目录中是否有同名的 .m 文件。

从结果中排除：

• 现有忽略文件已覆盖的模式
• MATLAB 已自动排除的模式（.git/、.svn/、.buildtool/、*.asv、resources/project/、*.prj）

第 4 步 — 呈现

仅显示新的建议——即存在、尚未排除且应该排除的文件。不要列出已经处理的内容或未找到的内容。不要显示内部推理、验证说明或有关检测过程的评论。按命名的类别标题分组显示建议：

## Ignore Suggestions — [Toolbox Name]

### OS / IDE Metadata
| # | Pattern | Found | Reason |
|---|---------|-------|--------|
| 1 | *.DS_Store | 3 files | OS metadata not useful to end users |
| 2 | .vscode/ | 1 folder | IDE settings |

### Test Infrastructure
| # | Pattern | Found | Reason |
|---|---------|-------|--------|
| 3 | tests/ | 12 files | Test files inside toolbox folder |

### Source Protection
| # | Pattern | Found | Reason |
|---|---------|-------|--------|
| 4 | myFunc.m | paired with myFunc.p | Source alongside pcode — excluding protects IP but removes help text access |

如果没有找到新的建议，只需说明：“没有其他排除项建议。”

对于 pcode 建议，请附上此说明：

排除具有匹配 .p 文件的 .m 文件可以保护源代码不被分发。不过，除非 pcode 是使用保留帮助文本的方式生成的（在包含帮助文本块的 .m 文件中运行 pcode -inplace），否则最终用户无法使用 help functionName。

第 5 步 — 询问

提示：要包含哪些建议？

A) 全部 — 包含所有建议 B) 所有 HIGH — 仅包含影响较大的项目 C) 选择 — 选择特定编号（例如“1, 2, 4”） D) 跳过 — 不创建或修改忽略文件

第 6 步 — 写入

使用 MATLAB 风格的注释（%），按类别分组，将选定的模式创建或追加到 toolbox.ignore。

注意： 在 MATLAB R2025a+ 中，toolbox.ignore 会触发弃用警告。如果用户有此偏好，可提供将文件命名为 package.ignore 的选项。

输出示例：

% toolbox.ignore
% Files excluded from toolbox packaging

% OS metadata
*.DS_Store

% IDE settings
.vscode/

% Test files (not distributed to end users)
tests/

% Source excluded (distributed as pcode)
myFunc.m

检查点

是 — 始终先呈现建议并等待用户选择，然后再写入任何内容。

关键规则

• 绝不要建议忽略工具箱文件夹中不存在的文件
• 绝不要建议忽略 MATLAB 默认排除项已处理的模式
• 如果现有忽略文件已涵盖某个模式，则跳过
• 找到 .p/.m 文件对时，始终显示 pcode 权衡说明
• 生成的文件使用 % 作为注释（MATLAB 约定）
• 在包含现有忽略文件的文件夹中再次运行时，只建议新增项

---

版权所有 2026 The MathWorks, Inc.

---