游戏引擎 / 系统课时
命令行构建怎样接入 CI
命令行构建怎样接入 CI
把 Cocos Creator 接入 CI,关键是固定编辑器环境、构建参数和产物位置,并让流水线准确识别构建结果。本课以 Cocos Creator 3.8 的 Web Mobile 目标为例,完成从代码提交到产物归档的可复用流程。
学习目标
- 确认命令行构建所需的编辑器环境和参数。
- 正确处理 Cocos Creator 的特殊成功退出码。
- 在 GitHub Actions 中触发构建并保存通过检查的产物。
先固定运行环境
Cocos Creator 3.8 支持 --project 和 --build 命令行参数,但命令行运行仍需要可用的图形会话,不能直接等同于完全无界面构建。这里选用已安装 Creator、完成首次启动、且能访问桌面会话的 macOS 自托管 Runner;普通无图形容器不应作为默认方案。
CI 工作目录必须是包含有效 Cocos 项目和启动场景的仓库根目录。固定编辑器小版本,提前恢复项目所需的扩展和依赖;若资源使用 Git LFS,还应确保检出的是实际资源而不是指针文件。把编辑器可执行文件的绝对路径配置为仓库变量 COCOS_CREATOR_BIN,不要假设所有机器安装路径相同。
构建链路中的失败要尽早阻断:编辑器执行失败、目标目录不存在或 Web 入口文件为空,都不能进入产物上传阶段。

用脚本统一构建与退出码
platform=web-mobile 确定平台,debug=false 关闭调试构建,buildPath=project://build 与 outputName=ci-web-mobile 固定产物目录为项目下的 build/ci-web-mobile。脚本放在仓库的 ci/build-web.sh,由 CI 和开发机共同调用。
Cocos Creator 3.8 文档规定,命令行构建成功的退出码是 36,参数错误是 32,构建错误是 34。因此不能让普通的 set -e 直接把返回 36 的编辑器进程判为失败;先捕获退出码,再转换成 CI 使用的 0 或 1。
#!/usr/bin/env bash
set -euo pipefail
: "${CC_CREATOR:?请设置 CC_CREATOR 为编辑器可执行文件的绝对路径}"
project="$(cd "${1:-.}" && pwd)"
output="$project/build/ci-web-mobile"
# 仅删除本次目标目录,避免旧产物让检查误通过。
[[ -x "$CC_CREATOR" ]] || { echo "找不到可执行的 Creator" >&2; exit 1; }
rm -rf "$output"
# 官方约定 36 表示成功,必须先接住非零退出码。
if "$CC_CREATOR" --project "$project" \
--build "platform=web-mobile;debug=false;buildPath=project://build;outputName=ci-web-mobile"; then
code=0
else
code=$?
fi
[[ "$code" -eq 36 ]] || { echo "BUILD_FAILED code=$code" >&2; exit 1; }
[[ -s "$output/index.html" ]] || { echo "BUILD_FAILED missing index.html" >&2; exit 1; }
printf 'BUILD_OK artifact=%s\n' "$output"预期输出(仅展示脚本最后一行,编辑器日志省略):
BUILD_OK artifact=<PATH>/build/ci-web-mobile<PATH> 是实际项目绝对路径。若失败,脚本退出码为 1;流水线会停止当前构建步骤,不能因为旧目录存在而误报成功。
将构建与归档接入流水线
以下是完整的 GitHub Actions 工作流配置,保存为 .github/workflows/cocos-web.yml。自托管 Runner 已配置好图形会话,仓库变量 COCOS_CREATOR_BIN 指向对应的 Creator 可执行文件;脚本与项目代码一起提交。
name: Cocos Web Build
on:
push:
workflow_dispatch:
jobs:
web-mobile:
runs-on: [self-hosted, macOS]
timeout-minutes: 60
steps:
- uses: actions/checkout@v4
- name: Build Web Mobile
env:
CC_CREATOR: ${{ vars.COCOS_CREATOR_BIN }}
run: bash ci/build-web.sh "$GITHUB_WORKSPACE"
- name: Upload build
uses: actions/upload-artifact@v4
with:
name: cocos-web-mobile
path: build/ci-web-mobile/
if-no-files-found: error预期结果是每次推送触发一次构建作业,脚本判定成功且 index.html 非空时才出现名为 cocos-web-mobile 的 Artifact;构建失败则作业失败,不上传不完整的包。首次运行时应核对该 Artifact 内确实包含网页入口、脚本和资源,而非只有空目录。
出错时先检查什么
如果构建进程启动不了,优先检查 Runner 登录用户能否直接执行同一编辑器路径,以及是否具备图形会话访问权限。如果返回 32,检查平台名称、参数拼写与项目路径;返回 34,查看 Creator 构建日志、扩展报错和依赖资源。若返回 36 但缺少 index.html,核对 buildPath、outputName 和目标平台,不能直接跳过文件校验。
不同 Creator 版本或复杂平台参数,优先使用构建面板导出的配置并通过 configPath 指定,避免手工猜测扩展字段。具体参数和退出码可对照官方命令行发布说明。CI 能保证过程可重复,但产物是否满足实际发布要求,还需要针对目标平台继续校验内容与包体。