企业官网建设流程全解析

1. 为什么需要 Model Reference 模块

1.1 模型复用与协同建模的痛点

在 Simulink 中做复杂系统建模时，很多工程师一开始都是把所有功能堆在同一个模型里。需求简单的时候问题不大，但随着模型变大，比如同时包含电机控制、电池管理、车辆动力学、热管理等多个子系统，麻烦就会一个接一个地出现。

首先是多人协同的问题。同一个模型文件里，两个人同时修改就会出现版本冲突，经常是 A 刚改完总线信号定义，B 又覆盖了一版，辛苦改好的接口对不上。其次是复用问题。项目 A 已经验证过的控制算法，项目 B 想直接用，传统做法是复制一个同样的子系统过来。可一旦算法更新，所有复制过的模型都要手动同步，漏掉一个就可能导致多个项目行为不一致。更麻烦的是代码生成，模型庞大之后，每次生成代码都要全量编译，一个小参数改动往往要等很久。

这时候就需要 Model Reference（模型引用）模块来解决这些问题。它让模型能够在文件级别被独立管理、独立复用、独立构建，是 Simulink 在中大型工程和团队开发中的核心手段。

1.2 Model Reference 模块是什么

Model Reference 是 SimulinkPorts & Subsystems（端口与子系统）模块库中的一个重要模块。它提供一种“模型级复用”的能力：在父模型（Parent Model）中放置一个 Model 模块，通过该模块引用另一个独立的.slx或.mdl模型文件。被引用的模型称为被引用模型（Referenced Model）。

父模型并不会把被引用模型的内部实现复制过来，而是建立一种引用关系。仿真或代码生成时，Simulink 会直接加载被引用模型的计算逻辑，外部只能看到这个模型暴露出来的输入输出端口，看不到内部结构，也无法直接访问内部信号。

这种机制带来的直接好处有三个：一是模型文件独立，版本管理更清晰；二是多个模型可以并行开发，互不阻塞；三是构建和代码生成可以增量进行，被引用模型没有变化时，不需要重新编译。

1.3 与 Subsystem、Library 的核心区别

很多初学者第一次看到 Model Reference 时，会自然地想到 Subsystem（子系统）和 Library（库模块）。它们确实都解决“复用”问题，但使用场景差异很大。

从表格可以看出，Subsystem 适合在一个模型内部做结构化拆分，Library 适合共享通用模块，而 Model Reference 更适合被多个项目或者多个团队复用的完整算法单元。实际项目中，三者经常组合使用，并不互斥。

2. Model Reference 的工作机制

2.1 被引用模型与父模型的关系

在 Model Reference 架构中，模型之间的关系是“父子”关系：父模型通过 Model 模块引用被引用模型。被引用模型通过 Inport（输入端口）和 Outport（输出端口）定义对外接口，父模型通过连线与这些端口交换信号。

由于被引用模型是独立文件，父模型不能直接使用 Goto/From 标签来访问被引用模型内部的信号。如果确实需要监视中间变量，有几种方案：把需要的信号引出为调试输出端口、使用信号记录（Signal Logging）、或者在调试阶段临时打开被引用模型观察。这种边界限制其实是一种保护机制，它强制建模者把接口设计清楚，不会因为内部改动破坏外部连接。

另外，被引用模型的参数可以存放在模型工作区（Model Workspace）或数据字典（Data Dictionary）中，父模型默认无法直接访问这些内部参数。如果需要在父模型侧配置被引用模型的某些参数，可以使用 Model 模块的Parameters选项卡进行参数映射，或者通过Simulink.Parameter对象配合数据字典实现共享。

2.2 仿真模式：Normal、Accelerator、Rapid Accelerator

Model Reference 支持多种仿真模式，这也是它与普通子系统差异较大的地方。在 Model 模块参数对话框中，Simulation mode选项可以设置为：

• Normal（正常模式）：被引用模型以较常规的方式参与仿真，便于调试，可以进入被引用模型内部查看信号。首次仿真时，Simulink 仍会在工作目录的slprj文件夹中生成仿真目标缓存，用来描述被引用模型的接口和依赖关系。Normal 模式对模型本身的改动不敏感，适合开发调试阶段。
• Accelerator（加速模式）：被引用模型会被编译生成 C 代码，仿真运行时直接执行编译后的代码，速度明显提升。这种模式适合仿真逻辑基本稳定、需要反复执行验证的场景。
• Rapid Accelerator（快速加速模式）：整个父模型以外部模式或快速加速方式运行，被引用模型可以复用目标代码。多个实例共用同一个被引用模型时，这种模式的构建优势最明显，特别适合参数扫描、批量仿真和硬件在环（HIL）准备。

选择仿真模式的核心思路是：开发初期用 Normal 方便调试，仿真验证阶段用 Accelerator 或 Rapid Accelerator 提升效率。需要注意的是，切换到 Accelerator 模式通常需要编译器环境正常，否则会出现仿真目标构建失败的问题。

2.3 信号边界与数据字典

Model Reference 的另一个关键点是“边界”。被引用模型的输入端口必须和父模型连接信号的数据类型、维度、采样时间完全匹配。如果被引用模型内部使用int16数据类型，父模型连接的是double，Simulink 会报错或自动做类型转换，具体取决于信号转换配置。

数据字典方面，被引用模型可以关联自己的.sldd数据字典文件，例如定义参数对象、信号对象、总线对象等。如果在仿真时出现“找不到数据字典 xxx.sldd”的错误，多半是字典文件路径失效或该模型不再关联这个字典，这个坑在团队协作中非常常见。后面第 5 章我们会专门讲排查方法。

3. 创建 Model Reference 的完整实操

下面通过一个具体案例，演示如何从零搭建一个 Model Reference 模型。例子采用一个比例控制器（P 控制器）作为被引用模型，父模型模拟一个简单速度控制场景。

3.1 创建被引用模型

先创建一个独立的 Simulink 模型文件，命名为speed_controller.slx。该模型包含两个输入端口（目标速度ref_speed、当前速度cur_speed），一个输出端口（控制量control_u），内部用求差模块计算误差，再用增益模块kp放大误差作为控制量。

在 Simulink 编辑器中操作，步骤如下：

1. 新建模型，保存为speed_controller.slx。
2. 从Ports & Subsystems模块库中拖入两个 Inport 和一个 Outport。
3. 从Math Operations模块库中拖入一个 Sum 模块。
4. 从Math Operations模块库中拖入一个 Gain 模块。
5. 修改端口名称，例如ref_speed、cur_speed、control_u。
6. 双击 Sum 模块，把符号设置为+-，表示第一个输入减去第二个输入。
7. 双击 Gain 模块，设置 Gain 值为2.5。
8. 连接信号：ref_speed连到 Sum 的第一个输入，cur_speed连到 Sum 的第二个输入，Sum 输出连到 Gain，Gain 输出连到control_u。
9. 保存模型。

如果你习惯用命令行创建，可以参考下面这段 MATLAB 脚本，思路完全一致：

% 创建被引用模型 speed_controller.slx new_system('speed_controller'); open_system('speed_controller'); % 添加输入输出端口 add_block('built-in/Inport', 'speed_controller/ref_speed'); add_block('built-in/Inport', 'speed_controller/cur_speed'); add_block('built-in/Sum', 'speed_controller/error'); add_block('built-in/Gain', 'speed_controller/kp'); add_block('built-in/Outport', 'speed_controller/control_u'); % 配置端口和增益 set_param('speed_controller/error', 'Inputs', '+-'); set_param('speed_controller/kp', 'Gain', '2.5'); % 连线 add_line('speed_controller', 'ref_speed/1', 'error/1'); add_line('speed_controller', 'cur_speed/1', 'error/2'); add_line('speed_controller', 'error/1', 'kp/1'); add_line('speed_controller', 'kp/1', 'control_u/1'); % 保存 save_system('speed_controller');

注意：add_block中使用的built-in/Inport、built-in/Sum等是 Simulink 内部模块路径，不同语言版本下显示名称可能不同，但代码中的内部标识一般保持一致。如果命令行报错，优先在图形界面中手动添加即可。

3.2 在父模型中添加 Model 模块

接下来创建父模型vehicle_level.slx，用来引用刚刚创建的speed_controller模型。

操作步骤如下：

1. 新建模型，保存为vehicle_level.slx。
2. 打开 Simulink Library Browser（库浏览器），在Ports & Subsystems中搜索Model模块。
3. 把Model模块拖入父模型画布。
4. 双击 Model 模块，在Model name一栏填写speed_controller，点击确定。
5. 此时 Model 模块会自动显示speed_controller的输入输出端口，分别是ref_speed、cur_speed和control_u。
6. 在父模型中添加两个 Inport 和一个 Outport，分别连接到 Model 模块对应的端口上。
7. 保存父模型。

命令行方式也可以实现：

% 创建父模型并添加 Model 模块 new_system('vehicle_level'); open_system('vehicle_level'); add_block('built-in/Inport', 'vehicle_level/ref_speed'); add_block('built-in/Inport', 'vehicle_level/cur_speed'); add_block('built-in/Outport', 'vehicle_level/control_u'); % 添加 Model 模块并指定被引用模型 add_block('simulink/Ports & Subsystems/Model', 'vehicle_level/speed_controller_ref'); set_param('vehicle_level/speed_controller_ref', 'ModelName', 'speed_controller'); % 连线 add_line('vehicle_level', 'ref_speed/1', 'speed_controller_ref/1'); add_line('vehicle_level', 'cur_speed/1', 'speed_controller_ref/2'); add_line('vehicle_level', 'speed_controller_ref/1', 'control_u/1'); save_system('vehicle_level');

3.3 设置被引用模型的仿真参数

如果你希望被引用模型以加速模式运行，可以在父模型中双击 Model 模块，在Simulation mode下拉框中选择Accelerator或Rapid Accelerator。

此外，在父模型的Model Configuration Parameters中，有一个Model Referencing配置页，建议按下面的思路设置：

• Rebuild options（重建选项）：建议保持默认的If structure or underlying content has changed。这会保证被引用模型内容变化后自动重建仿真目标，内容没变则直接复用，兼顾正确性和效率。
• Enable parallel builds（启用并行构建）：如果电脑是多核处理器，且项目中存在多个被引用模型，可以勾选，减少总构建时间。
• Number of workers（并行工作进程）：根据需要调整，不要设置过大，避免内存占用过高。

配置完成后，点击父模型工具栏的Run按钮进行仿真。首次仿真会因为需要构建被引用模型的仿真目标而稍慢，后续没有变化时就会直接使用缓存结果，速度显著提升。

3.4 将已有 Subsystem 转换为 Model Reference

如果你已经写好了子系统，想把它转成 Model Reference，可以使用 Simulink 提供的转换功能。

在比新版本的 MATLAB 中，选中 Subsystem 模块后，可以右键选择Refactor Model或Convert Subsystem to Model Reference，之后填写生成的新模型名称，Simulink 会自动完成转换。不同 MATLAB 版本的菜单位置有所差异，如果找不到这个选项，可以检查当前模型是否处于“非保护”状态，以及版本是否支持该功能。

转换完成后，原来 Subsystem 内部的 Inport/Outport 会自动对齐，外部连线保持不变，体验比较顺畅。但要注意，如果 Subsystem 内部使用了 Goto/From 跨越父模型共享信号，转换可能会报错，需要先调整信号接口。

4. Model Reference 常用配置与参数详解

4.1 Model 模块参数对话框

双击 Model 模块后，可以看到几个关键选项卡：

• Model name（模型名称）：指定被引用模型的文件名。点击右侧的浏览按钮可以选择当前路径或 MATLAB 路径下的模型。
• Parameters（参数）：用于把父模型工作区中的变量映射给被引用模型的参数。如果被引用模型定义了Simulink.Parameter对象，或使用了模型工作区变量，可以在这里建立映射关系。
• Ports（端口）：显示当前被引用模型暴露出的输入输出端口及顺序，可以快速了解接口匹配情况。
• Metadata（元数据）：显示被引用模型的版本、路径等信息，适合排查版本不一致问题。

4.2 采样时间与代数环

被引用模型的端口采样时间必须是显式的，要么在端口上直接指定采样时间，要么允许 Simulink 根据模型内部逻辑自动推断。如果父模型信号采样时间与被引用模型不一致，Simulink 会通过“有效采样时间传播”机制进行匹配，但有时候会报采样时间不一致的错误。推荐的做法是，在 Inport 模块的Sample Time参数中明确设置采样时间，比如0.01，避免歧义。

代数环（Algebraic Loop）在 Model Reference 中也很常见。如果被引用模型输入到输出之间存在直通路径，而父模型又把输出反馈回输入，就容易形成代数环。排查时可以在诊断信息中定位到代数环所在的模块路径，尝试在环中增加 Unit Delay、Memory 模块或者调整代数环求解器选项。

4.3 代码生成中的模型引用

如果最终目标是生成 C 代码，Model Reference 的价值更加明显。

在配置参数中，把System target file设置为ert.tlc（Embedded Coder），然后启用代码生成。被引用模型会生成独立的 C 函数，例如speed_controller_step()和speed_controller_initialize()。如果父模型中同一个被引用模型被使用了多次，还可以在代码生成选项中启用Model reference reuse，让多个实例共用同一份代码函数，只是传进去的实例参数不同，这样能明显减小生成代码的体积，也更适合嵌入式场景。

需要说明的是，代码生成的详细配置与目标编译器、硬件平台强相关，实际工程中不建议直接套用他人配置，应该按照项目的 Target 配置文档来设置。

4.4 子模型与模型工作区

被引用模型内部可以使用模型工作区（Model Workspace）存放参数，例如 PID 增益、滤波器系数等。模型工作区中的变量可以定义成Simulink.Parameter对象，并设置存储类（Storage Class），这样在代码生成时可以直接映射到全局变量或宏定义。

父模型默认看不到模型工作区的内容。如果你觉得这个限制太严格，可以把需要共享的参数集中放到一个数据字典中，父模型和被引用模型都关联同一个字典文件，这样两边就都能访问同一组参数对象，既保持接口清晰，又兼顾参数共享。

5. 常见错误与排查思路

Model Reference 虽然好用，但在实际项目中遇到的问题也不少。下面整理了几类高频问题，并给出排查顺序。

5.1 找不到数据字典

这是团队协作中最常见的错误之一，尤其是在使用 Git 或 SVN 管理模型文件时。某个被引用模型本来关联了can.sldd，但同事拿到代码后，字典文件没有同步到本地，或者路径变了，Simulink 打开模型时就报“找不到数据字典”的错误。

排查步骤建议如下：

1. 检查报错信息中提到的字典文件在本地是否存在。
2. 如果存在，确认当前模型关联的字典路径是否正确。可以在模型属性（Model Properties）中的Data Dictionary栏查看。
3. 如果路径错误，使用Simulink.DataDictionary.open('xxx.sldd')手动打开字典，然后重新关联。
4. 如果字典文件缺失，需要从版本库同步，或者与创建字典的同事确认文件位置。

更好的做法是把数据字典文件放在与模型同级的固定目录中，并使用相对路径引用，避免不同电脑上绝对路径不一致。

5.2 仿真目标构建失败

仿真目标（Simulation Target）构建失败的表现是：点击 Run 后，进度条在“Building Simulation Target”阶段卡住或弹出红色错误。

常见原因有三个：

• 本机没有安装可用的 C 编译器。运行mex -setup查看当前编译器情况，如果提示找不到编译器，需要安装 MinGW-w64 或 Visual Studio Build Tools。
• MATLAB 路径中包含中文、空格或特殊字符，导致编译临时文件路径异常。建议把整个工作目录调整到纯英文路径。
• 之前构建产生的slprj缓存损坏。可以删除当前工程目录下的slprj文件夹，重新仿真，让 Simulink 重新生成缓存。

5.3 端口类型与维度不匹配

Model Reference 对接口匹配要求比较严格。被引用模型的 Inport 如果设置成double类型、1x1维度，父模型连接了一个int16类型或4x1维度的信号，仿真时就会报错。

解决办法是在父模型中使用 Signal Conversion 模块、Data Type Conversion 模块进行显式转换。更推荐的做法是：在项目早期就统一信号类型规范，例如所有物理量使用double，枚举量使用Simulink.Bus总线对象，这样接口匹配问题会大幅减少。

6. Model Reference 工程最佳实践

6.1 为每个被引用模型建立独立数据字典

在复杂项目中，建议每个被引用模型都关联一个独立的数据字典，而不是把所有参数都放到父模型工作区。这样做的好处是：模型自包含、可移植、方便团队并行修改。例如speed_controller.slx对应speed_controller.sldd，里面定义控制器的全部参数和信号对象。

需要注意的是，数据字典的引入也带来了文件同步的工作量。使用版本控制时，.sldd文件必须和.slx文件一并提交，否则同事拉取代码后会遇到数据字典缺失的报错。

6.2 接口设计要稳定

Model Reference 的接口一旦确定，后续修改成本会比较高。所以在设计被引用模型时，要格外重视输入输出接口：

• 输入输出端口数量尽量精简，只暴露必须的信号。
• 端口顺序固定，且建议在端口名称中体现物理含义。
• 优先使用Simulink.Bus定义总线信号，减少端口数量。
• 数据类型、采样时间要在建模初期明确，避免后期大量转换。

一个稳定接口的核心是“变化尽量发生在内部，接口保持长期稳定”。这样其他团队在集成时不会被频繁变更打断。

6.3 合理利用增量构建

Model Reference 的增量构建能力是替代 Subsystem 的重要理由。使用时要注意：

• 不要频繁修改被引用模型的结构（增删端口、改变内部模块连接），因为结构变化会导致更多模型需要重新构建。
• 只修改参数值时，可以优先通过 Model 模块的 Parameters 映射传入，而不是直接修改被引用模型内部。
• 在 CI 自动构建脚本中，可以设置 Rebuild 选项为按需构建，以节省时间。

6.4 代码生成阶段注意事项

在嵌入式代码生成项目中，Model Reference 通常配合 Embedded Coder 使用。一些工程建议包括：

• 为每个被引用模型配置独立的代码生成目录，便于排查生成的.c、.h文件。
• 在代码生成前执行模型检查，使用 Model Advisor 检查模型规范和代码生成兼容性。
• 如果被引用模型被复用多次，务必确认代码生成选项中的实例复用配置，避免生成重复函数。

常见的一种做法是：父模型只负责系统集成和调用关系，真正的算法全部放在被引用模型中生成独立函数。这样维护算法时，只需要重新生成被引用模型的代码，不会影响整个系统的代码结构。

6.5 团队协作与版本管理

多人建模时，建议遵循以下协作规则：

• 每位工程师负责一个或多个被引用模型，不要在同一个模型文件上频繁合并修改。
• 父模型统一保存到独立的目录，例如models/integration/，被引用模型保存在models/components/。
• 提交代码时同时提交.slx、.sldd、slprj的忽略规则，避免缓存文件进入版本库。
• 在合并分支时，优先使用 MATLAB 自带的模型比较和合并工具（Simulink Model Comparison），不要直接手动编辑 XML 内容。

如果公司已经使用 Git，可以在 Git LFS 中管理模型文件，减少大文件冲突的概率。另外，每次修改模型前，最好用模型差异工具确认改动范围，降低无意识改动带来的风险。

7. 总结与下一步学习建议

到这里，关于 Model Reference 模块的核心内容就梳理完了。我们从模块库中的位置出发，对比了它与 Subsystem、Library 的区别，讲了它的工作机制，并通过一个速度控制器的例子完整演示了创建被引用模型、在父模型中引用、配置仿真模式和代码生成的过程。也整理了数据字典缺失、仿真目标构建失败、端口类型不匹配等高频问题的排查方案。

如果你正在从单体大模型向模型架构拆分转型，建议先挑一个边界清晰的算法单元，比如 PID 控制器、滤波器或状态观测器，把它转换为 Model Reference，先在一个模型内跑通，再逐步扩展到多模型协作。过程中注意观察slprj目录的构建日志和仿真速度变化，这些都是理解 Model Reference 底层行为的好素材。

接下来可以继续学习的方向包括：Simulink 数据字典的深入应用、Rapid Accelerator 模式下的参数批量扫描、Embedded Coder 的代码生成配置、以及如何用 Simulink Test 对 Model Reference 做单元测试和覆盖率分析。理解这些内容后，再把 Model Reference 用于实际项目，你会明显感受到它在团队协同和工程交付上的价值。