managing-simulink-projects

管理 Simulink 项目

MATLAB 项目用于协调 Simulink 工作流：它们管理 MATLAB 路径（Simulink 用它来解析模型引用、数据字典和需求），跟踪纳入源代码管理的文件，并提供基于标签的自动化功能，以便在 CI/CD 流水线中选择目标。

适用场景

• 为 Simulink 模型创建新的 MATLAB 项目
• 向现有项目添加模型、数据字典或需求
• 配置项目路径，以便 Simulink 解析引用
• 设置用于自动化的标签（测试选择、代码生成目标）
• 配置源代码管理和缓存文件夹
• 诊断损坏的模型引用、缺失的数据字典或未通过的项目健康检查

不适用场景

• 构建或编辑模型结构（模块、连接）→ 使用 building-simulink-models
• 编写或运行测试 → 使用 testing-simulink-models
• 起草需求内容 → 使用 generate-requirement-drafts
• 运行仿真进行分析 → 使用 simulating-simulink-models

基本概念

以下四项原则可避免最常见的问题：

1. 注册 ≠ 路径。 addFile 将文件注册到项目中，以便进行源代码管理跟踪。addPath 将文件夹添加到 MATLAB 路径，使 Simulink 能够按文件名解析工件。这是相互独立的操作——通常两者都需要。

2. 仅按文件名解析。 数据字典（set_param(...,'DataDictionary',...)、addDataSource）、模型引用和需求都通过 MATLAB 路径，仅使用文件名进行解析——绝不能使用完整路径。必须将包含文件的文件夹添加到项目路径。

3. addPath 不会递归添加路径。 每个包含可解析工件的子文件夹都需要单独调用 addPath。

4. 只能打开一个项目。 同一时间只能打开一个项目。创建或打开新项目会静默关闭当前项目（并运行其关闭脚本）。没有打开任何项目时，currentProject 会抛出错误，而不会返回空值。

防护措施

始终：

• 对每个包含数据字典、引用模型、需求或配置文件的文件夹使用 addPath(proj, folder)
• 向 addDataSource、set_param(...,'DataDictionary',...) 和 slreq.createLink 传递文件名（而非完整路径）
• 为 SimulinkCacheFolder 和 SimulinkCodeGenFolder 使用绝对路径：proj.SimulinkCacheFolder = fullfile(proj.RootFolder, 'work')
• 查询 proj.Dependencies 前调用 updateDependencies(proj)
• 创建或打开其他项目之前，先关闭当前项目
• 为 DependencyCacheFile 使用 .graphml 扩展名
• 使用 .gitignore 将派生文件排除在源代码管理之外
• 将需求链接到模型时，把需求文件夹添加到项目路径
• 将 .slmx 链接存储文件注册到项目中（使用 isfile 检查进行保护）

先行询问：

• 从项目中删除文件（先调用 removeFile，再从磁盘删除）
• 修改启动/关闭脚本（会影响所有打开该项目的用户）
• 更改项目引用（会影响依赖项目）

切勿：

• 使用 proj.IgnoredFilePatterns——对于通过 createProject 创建的所有项目类型，都会抛出“Feature not supported”错误
• 使用 cat.Labels——正确的属性是 cat.LabelDefinitions
• 将 'string' 用作标签 DataType——有效类型为 'none'、'char'、'double'、'integer'、'logical'
• 在 R2024a 及更高版本中使用单数形式的 findFile 查询标签——应使用复数形式的 findFiles。仅在 R2023a/b 中使用 findFile
• 向仅接受文件名的 API 传递完整文件路径
• 尝试同时打开两个项目
• 在启动脚本中使用 clear all——这会清除 proj 变量

任务路由

意图	参考文档
将文件/文件夹添加到项目，管理项目路径	references/path-and-file-management.md
为自动化流水线设置标签	references/labels-and-automation.md
将数据字典链接到模型	references/data-dictionaries.md
配置跨文件夹的模型引用	references/model-references.md
配置源代码管理、缓存文件夹、.gitignore	references/source-control-and-caching.md
配置启动/关闭脚本	references/path-and-file-management.md（“启动和关闭脚本”部分）
诊断损坏的引用或健康检查失败	从下方的验证开始，然后转到相关参考文档

验证

每次修改项目后运行：

results = runChecks(proj);
updateDependencies(proj);
deps = proj.Dependencies;  % digraph

如果 runChecks 报告问题，请检查项目路径中缺少哪些文件夹——这是大多数失败的根本原因。

---

版权所有 2026 The MathWorks, Inc.

---