4. CODESYS工程文件与版本控制
在CODESYS自动构建与测试工程中，版本控制不是“把工程丢进Git”这么简单。CODESYS工程由多种文件类型组成，其中既有可读的XML/文本描述，也有二进制编译产物和库引用。理解这些文件的差异，才能设计出可协作、可审查、可自动构建的版本控制方案。
一、核心原理：CODESYS工程文件格式与版本控制边界
CODESYS工程通常以.project为入口，内部包含设备树、POU、任务配置、库引用、可视化页面等对象。不同对象的存储方式不同，直接影响Git的合并与审查能力。
- 文本化对象：如ST、CFC、SFC等POU在启用“文本导出”或使用
.export格式时，可生成可读的XML或ST文本，适合Git diff与代码审查。 - 二进制对象：如
.project、.library、编译生成的.compileinfo等，Git只能识别“二进制文件已更改”，无法逐行合并。 - 库与设备描述：设备描述文件、库文件通常体积大且由厂商维护，应通过包管理器或固定版本引用，而不是直接提交到业务仓库。
因此，在工程根目录应配置.gitignore，排除编译中间件、日志、临时导出文件，只保留源工程与必要的文本导出。
# .gitignore 示例
*.compileinfo
*.precompile
*.log
*.tmp
__pycache__/
Build/
_Export/
*.library
二、Git集成：从工程目录到自动构建流水线
CODESYS本身不内置Git客户端，但可以通过“工程导出为文本”或“CODESYS Git插件”实现集成。推荐做法是：在开发机上使用Git管理工程目录，在CI流水线中使用CODESYS命令行工具进行无头构建。
- 初始化仓库：在工程根目录执行
git init，添加.gitignore，首次提交只包含源工程和文本导出。 - 文本导出：使用CODESYS的“导出工程”功能，将POU导出为
.export或.xml，便于diff。 - 分支开发：每个功能或修复在独立分支进行，避免多人同时修改同一二进制工程文件。
- CI构建：在流水线中调用
CODESYS.exe --project=... --build，生成可执行文件并运行测试。
# CI 中调用 CODESYS 命令行构建
CODESYS.exe --project="MyProject.project" --build --noUI
三、分支策略与代码审查：让变更可追溯
对于PLC工程，推荐采用“主干保护 + 短生命周期功能分支”的策略。主干（main）始终保持可构建、可测试；功能分支从main切出，完成后通过合并请求（Merge Request）合入。
| 分支类型 | 命名示例 | 用途 | 合并要求 |
|---|---|---|---|
| main | main | 稳定可发布版本 | 仅通过MR合入，CI必须通过 |
| 功能分支 | feature/pid-tuning | 开发新功能或修改逻辑 | 至少1人审查，CI通过 |
| 修复分支 | fix/io-mapping | 紧急缺陷修复 | 快速审查，回归测试通过 |
| 发布分支 | release/v1.2 | 版本冻结与现场发布 | 仅接受缺陷修复 |
代码审查应聚焦于：变量命名与注释、任务周期与优先级、库版本变更、IO映射修改、安全逻辑。对于二进制工程文件，审查者应要求提交者同时提供文本导出或变更说明，否则无法有效评审。
.project二进制文件作为唯一提交内容。这样Git无法合并，冲突时只能“二选一”，极易丢失他人修改。
四、变更管理与复盘：从提交信息到可追溯发布
变更管理要求每次提交都能回答“改了什么、为什么改、影响哪些设备”。建议使用结构化提交信息，并在CI中自动生成变更日志。
# 提交信息模板
feat(pid): 增加PID自整定参数
fix(io): 修正DI03通道映射错误
docs(readme): 更新构建步骤
在自动构建流水线中，可将Git提交哈希写入编译产物版本号，便于现场问题追溯。例如在CODESYS工程中定义全局常量GIT_COMMIT，由CI脚本注入。
# CI 注入版本信息
echo "GIT_COMMIT=$(git rev-parse --short HEAD)" >> build.env
复盘时重点关注：分支是否过长导致合并困难、审查是否流于形式、二进制文件是否频繁冲突、库版本是否被意外升级。通过持续优化.gitignore、文本导出策略和CI检查项，可以显著降低协作成本。
总结来看，CODESYS工程版本控制的核心是“文本化、分支化、自动化、可追溯”。把可读对象交给Git，把二进制产物交给CI，把审查和变更记录固化到流程中，才能让自动构建与测试真正落地。