游戏引擎 / 系统课时

命令行构建怎样接入 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 入口文件为空,都不能进入产物上传阶段。

提交触发到构建产物归档的 CI 处理流程

用脚本统一构建与退出码

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。

bash
#!/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"

预期输出(仅展示脚本最后一行,编辑器日志省略):

text
BUILD_OK artifact=<PATH>/build/ci-web-mobile

<PATH> 是实际项目绝对路径。若失败,脚本退出码为 1;流水线会停止当前构建步骤,不能因为旧目录存在而误报成功。

将构建与归档接入流水线

以下是完整的 GitHub Actions 工作流配置,保存为 .github/workflows/cocos-web.yml。自托管 Runner 已配置好图形会话,仓库变量 COCOS_CREATOR_BIN 指向对应的 Creator 可执行文件;脚本与项目代码一起提交。

yaml
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 能保证过程可重复,但产物是否满足实际发布要求,还需要针对目标平台继续校验内容与包体。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

命令行构建怎样接入 CI

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通