3. PLCnext项目版本命名与编号规范设计

在PLCnext项目中，版本号不是给开发人员自己看的备注，而是贯穿项目模板、库文件、HMI画面、文档和交付包的“身份标识”。如果命名规则不统一，最常见的结果是：现场工程师拿到一个压缩包，无法判断它对应哪次硬件改版、是否包含某个关键修复、能否直接刷写到手头的AXC F 2152控制器上。因此，本节要解决的核心问题是：为PLCnext项目建立一套可读、可排序、可追溯的版本命名与编号规范，并把它固化到项目模板和文档中。

一、四层版本标识的分工

PLCnext项目通常同时存在多个维度的版本信息，建议把它们拆成四个独立字段，而不是混在一个字符串里：

• 语义化版本（SemVer）：面向功能与接口，格式为 主版本.次版本.修订号，例如 2.4.1。主版本在接口不兼容或工艺逻辑重大变更时递增；次版本在新增功能且向后兼容时递增；修订号在仅修复缺陷时递增。
• 内部版本：面向项目内部迭代，格式为 V主.次，例如 V2.4，用于把同一语义化版本下的多次内部构建归组，便于测试团队按批次管理。
• 构建号：由CI流水线自动生成，格式为 BYYYYMMDD.NNN，例如 B20250612.007，表示2025年6月12日的第7次构建。构建号只增不减，保证任何一次产物都可唯一定位。
• 硬件兼容标识：描述该版本可运行的控制器型号与固件范围，格式为 HW-型号-FW范围，例如 HW-AXC2152-FW2024.0+，表示适用于AXC F 2152，且要求控制器固件不低于2024.0。

四层字段组合后形成完整版本串，例如：2.4.1-V2.4-B20250612.007-HW-AXC2152-FW2024.0+。这个字符串既能在Git标签中使用，也能写入项目文档和交付清单。

二、编号规则的具体约定

要让规范可执行，必须把“什么时候递增哪一位”写成明确规则，而不是靠感觉。以下是一套可直接采用的约定：

硬件兼容标识的更新规则相对独立：只要目标控制器型号或最低固件要求发生变化，就必须更新该字段，即使语义化版本没有变化。例如从AXC F 2152迁移到AXC F 3152，硬件兼容标识应改为 HW-AXC3152-FW2024.0+，并在文档中记录迁移原因。

三、落地到项目模板

规范只有写进模板，才能被自动继承。在PLCnext Engineer中，建议在项目模板里预置以下内容：

1. 在全局变量表中声明四个版本字符串变量：gVersionSemantic、gVersionInternal、gVersionBuild、gVersionHardware，初始值留空，由构建脚本注入。
2. 在程序启动组织块（如 PlcTask 的初始化段）中，将四个变量拼接为 gVersionFull，供HMI和诊断页面读取。
3. 在库文件命名中强制使用语义化版本前缀，例如 Lib_MotorControl_2.4.1.pex，避免同名库文件覆盖。
4. 在项目根目录放置 version.json，由CI流水线写入构建号与硬件兼容标识，作为归档依据。

{
  "semantic": "2.4.1",
  "internal": "V2.4",
  "build": "B20250612.007",
  "hardware": "HW-AXC2152-FW2024.0+",
  "full": "2.4.1-V2.4-B20250612.007-HW-AXC2152-FW2024.0+"
}

四、落地到文档与交付

文档侧至少需要三处固定位置承载版本信息：版本变更记录表、交付清单和现场刷写确认单。版本变更记录表建议包含“版本串、日期、变更类型、影响范围、验证人”五列，每次发布必须新增一行，不允许覆盖历史行。交付清单中，版本串应与压缩包文件名一致，例如 ProjectLineA_2.4.1-V2.4-B20250612.007.zip。现场刷写确认单则要求工程师填写控制器实际固件版本，并与硬件兼容标识中的最低要求比对，若低于要求则禁止刷写。

最后需要强调的是，版本命名规范的价值不在于字符串本身多漂亮，而在于它能否让“代码—构建—交付—现场”四个环节使用同一个标识。只要四层字段分工清晰、递增规则明确、模板和文档同步落地，PLCnext项目的版本治理就有了可执行的基础。