跳到主要内容

可复现构建、产物晋级与回退

适用:一般游戏与知识站的 CI/CD 方法;游戏构建基线 Cocos Creator 3.8.8 + TypeScript,配置例子使用 GitLab CI 的通用机制。资料核查:2026-11-17。本节不包含私有服务器、账号、凭据或实际部署操作。

先把两种产物分开​

知识站产物是静态页面、脚本与样式;Cocos 微信产物是供开发者工具读取的平台工程;业务后端又有自己的服务与数据迁移。它们可共享源码仓库或发布记录,但不能用同一个绿色 build 状态替代全部验证。一个站点部署成功,不能说明小游戏包已编译、审核或发布。先明确每个流水线的输入、输出与下一位消费者。

可复现从固定工具开始:依赖锁文件、Node 版本、Cocos 编辑器补丁版本、资源元数据、构建配置与规则内容都要保留。Cocos 导入缓存可以加速,但不能成为唯一可用状态;定期用干净工作目录验证缺少本地缓存仍能构建。资源压缩工具与插件若影响产物,也需要记录版本或摘要。

流水线按失败成本排序​

先运行快而确定的检查,再运行耗时构建和场景验证。站点可检查类型、测试、内容链接与静态构建;游戏可检查规则测试、配置结构、资源引用与目标构建;平台编译和真机通常需要另外的工具及环境。失败要停在相应阶段,不要用忽略退出码让后续继续发布。检查项必须对应实际脚本,不能在配置里写不存在的命令。

# 片段示意:合并到已有流水线,脚本名以项目实际定义为准。
stages: [verify, package]
verify:
stage: verify
script:
- npm ci
- npm run typecheck
- npm test
package-site:
stage: package
script:
- npm ci
- npm run build
artifacts:
paths:
- build/

片段只展示静态站检查与产物保存,不包含目标发布。运行镜像或 Runner 的 Node 版本应在项目配置中固定。Cocos 构建任务应使用具备编辑器环境的受控 Runner,按官方命令行参数读取构建配置;不要把游戏包构建假定成普通 npm run build,也不要让多个任务同时改同一编辑器工作目录。

构建一次,验证与发布使用同一份​

测试通过后再重新构建一份“正式包”,可能因为时间、依赖或远程配置变化产生不同产物。更可靠的方式是构建候选产物,计算摘要,保存清单,然后让验证、审核和最终发布引用同一份。若必须重新构建,就视为新候选并重新确认受影响检查。产物唯一身份比文件夹叫 release 更可靠。

发布清单记录 sourceRevision、editorVersion、dependencyDigest、buildConfigDigest、contentVersion、artifactDigest 和验证状态。Source Map、构建日志、资源体积与测试报告一起归档,并设适当访问范围。缓存用于加速可以丢弃,产物用于追溯需要有留存策略,二者不能混用。长期发布包应放可管理的版本仓库,而不只依赖某次临时任务附件。

环境与秘密按用途隔离​

开发、测试与正式环境的 API 地址、平台项目标识、商业配置和凭据应分离。客户端中出现的任何内容都不能当作服务端秘密。发布凭据从 CI 的受控秘密机制提供,限制任务与环境访问,不写入源码、日志或构建清单。脱敏输出也要检查实际值是否可能通过命令回显、错误堆栈或压缩包泄漏。

外部贡献代码的普通检查不应直接获得正式发布权限。发布分支或版本标签、环境保护与项目权限按团队授权设置,不从教程推导具体组织规则。工具支持的保护项与可用范围随版本和套餐变化,接入时查当前官方说明。这里的重点是让权限与产物晋级边界清楚,而不是增加不必要的人工阻塞。

防止旧流水线覆盖新版本​

多个提交可能并行构建:新版本先完成,旧版本后完成,如果都写同一个目标就会意外倒退。发布目标应串行化,并在切换前检查候选是否仍有资格成为当前版本。GitLab resource_group 可限制同一资源的部署并发,但并发控制本身不等于版本新旧判定。记录部署的版本身份与顺序,防止不透明覆盖。

静态站可采用版本目录与原子切换的思路,先完整上传并校验,再切换入口,避免用户拿到半套文件。资源文件带内容哈希,HTML 与清单的缓存策略单独设计;新旧客户端仍可能引用旧资源,清理要留兼容窗口。小游戏的平台上传、审核和正式发布则遵守当前平台流程,不能由通用站点部署脚本替代。

回退不只是换回旧文件​

旧客户端可能读不了新存档,旧服务可能理解不了新订单状态,旧配置也可能引用已删除资源。发布前写明代码、资源、配置、协议与数据各自的回退条件。数据迁移优先考虑兼容式扩展和分阶段切换;不可逆迁移需要专门恢复方案,不能在事故中临时执行破坏性数据库回滚。

上线后执行短冒烟,核对对外展示版本、核心入口、网络与资源状态,再观察错误和业务指标。回退演练也在测试环境运行:让负责人拿清单恢复上一版本,并检查数据仍可读。没有演练的“可以回滚”只是计划,不是已验证能力。

候选产物要经历真实消费检查​

文件存在并不代表它能被下一环节使用。站点产物应由静态服务打开,检查入口、深层链接和资源路径;微信产物应被当前开发者工具正确导入,再执行平台编译。将消费者检查列为独立状态,能及时发现基础路径、目录层级和平台配置错误,而不是到正式发布才发现包放错位置。

保留一次从清单重新取得产物的演练。让另一位执行者只凭版本标识找到文件、校验摘要、打开报告并运行冒烟,不依赖构建者电脑上的临时目录。若做不到,说明归档与说明仍不足。可追溯性不是文件很多,而是关键证据能够对应同一个候选版本。

交给 AI 的任务与验收​

可复制任务:“为站点与 Cocos 微信产物分别设计 CI 阶段,复用现有脚本,固定工具与配置。生成产物清单并保存哈希、日志与测试报告;验证和发布引用同一候选,控制并发与旧版本覆盖。只输出通用配置与检查,不写私有地址、凭据或自动执行发布。”

验收干净工作目录可构建;检查失败阻止晋级;产物摘要能对上测试材料;并行旧任务不能覆盖新版本;回退说明覆盖资源与数据兼容;微信审核、上传与真机状态仍单独标记。所有未执行步骤保持未执行。

官方来源​