4. 项目文件与工作区管理

在 iQ-R 系列 PLC 的工程实践中，GX Works3 工程文件并不是一个单一文件，而是一个以工程目录为核心、由多个逻辑单元组成的结构化集合。理解这个结构，是做好版本治理的前提。很多现场问题——例如“为什么改了标签，程序却报未定义”“为什么两个程序块引用了同一个结构体，修改后一个正常一个异常”——本质上都源于对工程内部元素关联关系认识不清。

一、工程文件的物理与逻辑结构

GX Works3 工程通常以 .gx3 工程文件为入口，实际数据存放在与工程同名的目录中。该目录下包含若干子目录与文件，其中与版本治理最相关的是：程序块（Program）、全局标签（Global Label）、结构体定义（Structure）、参数（Parameter）以及模块配置（Module Configuration）。这些元素在工程内以引用关系相互连接，而不是彼此独立。

从逻辑上看，一个 iQ-R 工程可以划分为三个层次：

• 工作区层：即整个工程，是版本管理的最小完整单位。工作区包含所有程序块、标签、结构体、参数和模块配置。
• 程序块层：每个程序块（如 MAIN、SUB1、中断程序）是独立可执行的逻辑单元，拥有自己的局部标签和程序体。
• 数据定义层：全局标签和结构体定义属于跨程序块共享的数据契约，被多个程序块引用。

关键点在于：程序块可以独立修改，但全局标签和结构体的修改会影响所有引用它们的程序块。这就是版本关联管理的核心矛盾。

二、工作区、程序块与数据定义的版本关联

在版本治理中，必须区分两类变更：局部变更和契约变更。

局部变更指仅修改某个程序块内部的逻辑、局部标签或注释。这类变更不影响其他程序块，版本管理相对简单，只需记录该程序块的修改内容即可。

契约变更指修改全局标签、结构体定义或模块参数。这类变更会改变程序块之间的数据接口，所有引用该标签或结构体的程序块都必须重新验证。例如，将全局标签 g_StartBtn 的数据类型从 Bit 改为 Word，所有使用该标签的程序块都会出现类型不匹配错误。

因此，建议在工程中建立如下版本关联管理规则：

三、实际操作方法：如何查看和验证关联关系

在 GX Works3 中，可以通过以下方式查看元素之间的引用关系：

1. 打开“交叉引用”窗口（Cross Reference），输入全局标签名或结构体名，即可列出所有引用该元素的位置，包括程序块名、程序步号和指令类型。
2. 使用“程序块列表”查看每个程序块的编译状态。当全局标签或结构体被修改后，未重新编译的程序块会显示为“未编译”或“有错误”。
3. 通过“工程校验”功能（Project Check）对整个工作区进行一致性检查，系统会报告标签未定义、类型不匹配、结构体成员缺失等问题。

四、版本关联管理的工程实践

以一个典型的 iQ-R 工程为例：工程包含 MAIN、SUB1、SUB2 三个程序块，全局标签 g_MachineState 为 Word 类型，结构体 ST_Axis 包含 Position、Speed、Status 三个成员。MAIN 和 SUB1 引用了 g_MachineState，SUB1 和 SUB2 引用了 ST_Axis。

现在需要为 ST_Axis 增加一个成员 AlarmCode。这是一个契约变更，操作步骤如下：

1. 在结构体定义中新增 AlarmCode : Word 成员。
2. 执行工程校验，系统会提示 SUB1 和 SUB2 中所有 ST_Axis 实例需要重新编译。
3. 分别打开 SUB1 和 SUB2，确认新增成员不影响原有逻辑，必要时在程序中补充对 AlarmCode 的赋值或读取。
4. 重新编译整个工作区，确认无错误。
5. 将工作区版本号从 V1.2 提升至 V1.3，并在版本记录中注明“ST_Axis 新增 AlarmCode 成员，影响 SUB1、SUB2”。

如果只是修改 MAIN 程序块内部的一段逻辑，不涉及全局标签和结构体，则只需记录 MAIN 程序块的版本变化，工作区版本号可以不变，或仅作为补丁版本记录。

五、版本关联管理的检查清单

为便于日常执行，可参考以下检查清单：

• 修改前：确认变更对象属于局部变更还是契约变更。
• 修改前：对全局标签或结构体执行交叉引用查询，记录受影响程序块。
• 修改中：先改数据定义层，再改程序块层，顺序不要颠倒。
• 修改后：执行工程校验，确认无未定义标签、无类型不匹配。
• 修改后：重新编译所有受影响程序块，确认编译通过。
• 提交时：在版本记录中明确标注变更类型、影响范围和验证结果。

通过以上方法，可以将 iQ-R 工程中的工作区、程序块、全局标签和结构体纳入统一的版本关联管理框架，使每一次变更都可追溯、可验证、可回退。