4. PLCnext项目基线建立与初始版本入库

在上一节中，我们已经明确了版本治理的基本对象与边界。本节要解决的是一个更具体、也更关键的问题：如何把当前手上的 PLCnext 项目，变成一个真正受控的起点。这个起点就是“基线”。基线不是简单地把文件复制到 Git 仓库，而是对代码、配置、文档三类资产做一次有意识的冻结，并给它一个可追溯、可回退、可比较的标签。

基线建立有两种典型入口：一是从现有项目出发，项目已经在现场或实验室运行过，代码、库、设备配置、HMI 画面、文档散落在不同目录；二是从新建项目出发，工程刚创建，尚未接入真实设备。两者的处理策略不同，但目标一致：让仓库中的第一个受控版本，能够准确回答“这个版本对应什么硬件、什么固件、什么库、什么文档”。

一、先判断项目当前状态，再决定入库范围

在 PLCnext Engineer 中打开项目后，不要急于提交。先做一次“资产盘点”。建议按以下维度检查：

• PLC 项目文件：.plcproj 或工程目录中的 *.pou、*.gvl、*.dt 等源文件；
• 设备与网络配置：控制器型号、固件版本、IP 地址、PROFINET/EtherCAT 设备名与拓扑；
• 库与依赖：PLCnext 库版本、第三方库、AXL F 模块固件、OPC UA 服务器配置；
• HMI/Web 资源：画面文件、Web 面板、CSS/JS 资源；
• 文档：IO 清单、点表、网络拓扑图、调试记录、验收标准。

如果项目已经运行过，还要额外记录当前控制器中的实际运行版本。这一步非常关键，因为工程文件与控制器内运行的程序可能不一致。可以用 PLCnext Engineer 的“在线比较”功能，或通过 plcnext-cli 读取控制器信息，确认固件版本与项目设置是否匹配。

二、建立仓库结构：让代码、配置、文档各归其位

PLCnext 项目通常包含二进制工程文件和文本源文件。推荐采用“源文件优先、二进制受控”的策略。一个可用的仓库结构示例如下：

plcnext-project/
├── src/                    # PLCnext Engineer 工程源文件
│   ├── project.plcproj
│   ├── POU/
│   ├── GVL/
│   └── DeviceConfig/
├── hmi/                    # HMI 与 Web 资源
├── docs/                   # IO 清单、拓扑图、固件记录
│   ├── io-list.xlsx
│   ├── network-topology.md
│   └── firmware-matrix.md
├── scripts/                # 构建、导出、校验脚本
├── .gitignore
└── README.md

.gitignore 要排除临时文件、编译输出、日志和本地用户设置。例如：

*.tmp
*.log
*.bak
Build/
_Compile/
*.user

注意：如果工程中包含二进制库文件或固件包，应明确是否纳入版本控制。若纳入，需在 README 中记录其来源、版本和校验值；若不纳入，则必须在文档中写明获取方式，否则基线不完整。

三、首次入库：从工作区到受控提交

首次入库建议分三步走，避免一次性提交大量无关文件。

1. 初始化仓库并添加远程地址：在项目根目录执行 git init，然后关联公司 GitLab 或 GitHub 仓库。
2. 分批次提交：先提交 docs/ 和 README.md，再提交 src/，最后提交 hmi/ 和 scripts/。每次提交写清楚“新增什么、对应什么状态”。
3. 检查提交内容：用 git status 和 git diff --cached 确认没有误提交临时文件、密码或本地路径。

首次提交的 commit message 建议采用“基线初始化”语义，例如：

git add docs/ README.md
git commit -m "docs: 初始化项目文档与固件版本记录"

git add src/
git commit -m "feat: 导入 PLCnext 工程源文件与设备配置"

git add hmi/ scripts/
git commit -m "feat: 导入 HMI 资源与构建脚本"

这样做的目的是让历史记录本身具备可读性。后续如果发现某个文件缺失，可以快速定位到是哪一次提交引入或遗漏的。

四、标签策略：给基线一个不可变的名称

提交完成后，需要给这个受控起点打标签。标签是基线的“身份证”，必须唯一、可读、不可随意移动。推荐使用语义化版本加日期或阶段标识，例如：

• v0.1.0-baseline：首个受控基线，尚未经过现场验证；
• v1.0.0-factory：出厂版本，已通过验收；
• v1.0.1-hotfix-202506：现场修复版本。

打标签时使用附注标签，而不是轻量标签，因为附注标签会记录打标签人、时间和说明：

git tag -a v0.1.0-baseline -m "首个受控基线：包含 PLC 工程、HMI、IO 清单与固件记录"
git push origin v0.1.0-baseline

标签一旦推送，就不要删除或覆盖。如果基线需要修正，应新建一个提交并打新标签，而不是移动旧标签。这是版本治理中“不可变历史”的基本原则。

五、基线验证：确认标签与内容一致

打完标签后，必须做一次验证。验证不是重新打开工程看一眼，而是从仓库角度确认：

• 标签指向的提交是否包含全部三类资产；
• README 中记录的固件版本、控制器型号是否与工程配置一致；
• IO 清单中的点数是否与 PLCnext Engineer 中的变量表一致；
• 仓库中是否意外包含密码、许可证或本地绝对路径。

下面这张图展示了从现有项目或新建项目出发，经过资产盘点、仓库组织、首次提交、标签固化到基线验证的完整关系。它强调的不是线性步骤，而是“资产分类—受控提交—标签冻结—验证闭环”的结构。

验证通过后，这个标签就可以作为后续变更的起点。任何新的修改，都应从该标签对应的提交拉出分支或直接在主线上继续，但必须保证：基线标签永远指向那个已经确认过的快照。如果后续发现基线中缺少某个 IO 点表，正确做法是补充提交并打一个新标签，例如 v0.1.1-baseline，而不是删除或移动 v0.1.0-baseline。

六、从基线出发的后续变更原则

基线建立后，后续所有变更都应遵循“先提交、后打标签、再部署”的顺序。对于 PLCnext 项目，尤其要注意：工程文件与控制器运行版本必须通过标签关联。每次现场部署前，先确认当前部署的是哪个标签，部署后再用该标签记录控制器实际运行的版本。这样，当现场出现异常时，才能快速回答“当时运行的是哪个版本、对应哪些配置和文档”。

总结来说，本节的核心不是“把文件放进 Git”，而是建立一条可追溯的链条：项目状态 → 资产盘点 → 仓库结构 → 首次提交 → 附注标签 → 基线验证。这条链条一旦建立，后续的变更治理、版本对比和回退才有可靠的基础。