本文详解如何通过 CODESYS 内置 Python 脚本引擎实现项目自动化构建、部署及 CI/CD 集成（如 Jenkins），涵盖 build() 调用、活动应用获取、无 GUI 执行等核心实践。
本文详解如何通过 codesys 内置 python 脚本引擎实现项目自动化构建、部署及 ci/cd 集成（如 jenkins），涵盖 `build()` 调用、活动应用获取、无 gui 执行等核心实践。
CODESYS Scripting Engine 提供了完整的 Python API，使开发者能在不依赖图形界面的前提下，以编程方式操控工程生命周期——从打开项目、选择应用、触发编译，到生成可部署镜像。这正是实现 Jenkins 自动化流水线的关键基础。
✅ 基础构建脚本：编译当前活动应用
最简可行脚本仅需一行核心调用：
# build_active_app.py projects.primary.active_application.build()
该语句会触发 CODESYS 编译器对当前设为“活动应用”（Active Application）的 PLC 程序执行完整构建流程，并将结果（如 .cproj 中间文件、.cld 加载文件等）输出至项目 Build 目录。构建成功与否可通过返回值或日志判断（见下文异常处理）。
⚠️ 注意：projects.primary.active_application 必须已存在且有效。若项目未设置活动应用，此调用将抛出 AttributeError。建议先校验：
if not projects.primary.active_application:
raise RuntimeError("No active application set in the project.")? 获取并操作指定应用（多应用项目场景）
当一个项目包含多个应用（如 App_Main、App_Test），需显式定位目标应用再构建：
# build_by_name.py
target_app_name = "App_Main"
# 遍历所有子对象，筛选出 Application 类型对象
apps = [app for app in projects.primary.get_children() if app.is_application]
# 查找匹配名称的应用
target_app = next((a for a in apps if a.get_name(False) == target_app_name), None)
if not target_app:
raise ValueError(f"Application '{target_app_name}' not found.")
# 构建并检查结果
result = target_app.build()
if not result:
print("❌ Build failed. Check CODESYS output log for errors.")
else:
print("✅ Build succeeded.")? 无 GUI 模式运行脚本（CI/CD 关键步骤）
为在 Jenkins 或命令行中自动执行，需关闭 GUI 并指定项目路径：
- 确保项目未被其他 CODESYS 实例打开（否则脚本会立即失败）；
- 使用 CODESYS 命令行接口启动脚本：
# Windows 示例（假设 codesys.exe 在 PATH 中） codesys.exe --script "C:\path\to\build_active_app.py" --project "C:\myproject\MyProject.cproj" # Linux/macOS（需使用 CODESYS Runtime 或 Docker 化 CODESYS IDE） codesys --script /path/to/build.py --project /path/to/project.cproj
✅ 提示：--project 参数会自动调用 projects.open(project_path)，无需在脚本中重复写入；脚本输出（print()）将直接打印到终端 stdout，便于 Jenkins 解析构建日志。
? 完整自动化脚本示例（含错误捕获与日志）
# ci_build.py
from __future__ import print_function
def main():
try:
# 1. 确保有活动应用
app = projects.primary.active_application
if not app:
raise RuntimeError("Active application is not set.")
# 2. 执行构建
print("? Starting build for application: '{}'".format(app.get_name(False)))
success = app.build()
# 3. 输出结果
if success:
print("✅ Build completed successfully.")
else:
print("❌ Build failed — check CODESYS error log.")
return 1
except Exception as e:
print("? Script execution error: {}".format(str(e)))
return 1
return 0
# 入口点（Jenkins 可据此判断 exit code）
if __name__ == "__main__":
exit(main())? 重要注意事项
- 权限与独占性：脚本运行时，CODESYS 必须拥有对项目文件的读写权限，且项目不能处于被其他用户/进程打开状态（包括后台 CODESYS 进程）；
- 环境一致性：CI 环境中务必使用与开发环境完全相同版本的 CODESYS IDE（如 v3.5.18.0），避免因 API 差异导致脚本失效；
- 构建产物路径：默认输出位于 <ProjectDir>/Build/，可通过 projects.primary.get_build_path() 获取；
- 扩展能力：构建后可进一步调用 app.download_to_device()（需设备在线）或 app.generate_download_file() 导出 .cld 文件用于离线部署。
掌握上述模式后，即可将 ci_build.py 无缝接入 Jenkins Pipeline，配合单元测试（如 CODESYS Test Manager CLI）、版本归档与部署通知，构建端到端的工业自动化 DevOps 流水线。
