游戏引擎 / 系统课时

发布产物怎样归档和追溯

发布产物怎样归档和追溯

同一个版本在 Web、小游戏和原生渠道可能产生不同的交付包。若 CI 每次都覆盖旧文件,线上故障时便无法确认用户拿到的具体产物。本课建立按版本、平台、渠道和流水线批次分层的归档规则,保存源码提交与文件摘要,让查包、回滚和复现都有明确依据。

学习目标

  • 设计不会被后续构建覆盖的多平台归档路径。
  • 用 Git 提交、Creator 版本和 SHA-256 清单关联源码与产物。
  • 区分可以回滚的已发布文件与供重新构建的环境证据。

给每次交付一个唯一位置

建议用 版本/平台/渠道/流水线批次 四级目录。例如 release-archive/1.4.0/web-mobile/official/ci-0042/,其中 1.4.0 是业务版本,web-mobile 是构建目标,official 是分发渠道,ci-0042 是不可复用的构建批次。同版本、同渠道重新打包也必须产生新批次,不能覆盖上一份。

每个批次内部放 payload/(实际交付文件)与 manifest.json(追溯清单)。Cocos Creator 的 Build Path 可调整,build/web-mobile 只是本文示例路径,应以项目构建任务实际输出为准。对于 Android、iOS,编辑器生成的原生工程不等于最终可交付安装包;归档时还应收集后续原生编译、签名得到的最终包和必要的符号文件。

把文件与构建证据连起来

归档时先确定原始构建输出,再复制到独立批次目录,对归档副本逐文件计算 SHA-256。清单记录版本、平台、渠道、批次、Git commit 和实际 Creator 版本;后续拿到一个异常包,就能反查发布记录及其源码。源代码可重建,但原始交付字节不能用“重新编一次”代替。

构建产物到不可变归档的追溯数据流

用 Node.js 自动生成归档

下面的脚本适用于 Node.js 18 及以上版本,在 Git 工作区根目录执行。先在 Cocos Creator 构建面板完成 Web Mobile 构建,并确认 build/web-mobile 存在。保存脚本为 archive.mjs;CI 需要把真实 Creator 版本传给 COCOS_CREATOR_VERSION,正式流水线的批次号应来自 CI 作业编号。

js
import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { join, relative, sep } from 'node:path';

const [source, version, platform, channel, runId] = process.argv.slice(2);
const creatorVersion = process.env.COCOS_CREATOR_VERSION;
const dimensions = [version, platform, channel, runId];
// 只接受安全目录片段,防止不同渠道写进意外路径
if (!source || !creatorVersion || dimensions.some(v => !v || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v))) {
  throw new Error('参数缺失或归档维度含非法字符');
}
if (!existsSync(source) || !statSync(source).isDirectory()) throw new Error('构建目录不存在');
const commit = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
const target = join('release-archive', version, platform, channel, runId);
const staging = `${target}.staging`;
if (existsSync(target) || existsSync(staging)) throw new Error('批次已存在,拒绝覆盖');
const payload = join(staging, 'payload');
mkdirSync(staging, { recursive: true });
cpSync(source, payload, { recursive: true });

const files = [];
function collect(dir) {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) collect(full);
    else if (entry.isFile()) files.push({
      path: relative(payload, full).split(sep).join('/'),
      sha256: createHash('sha256').update(readFileSync(full)).digest('hex'),
    });
  }
}
// 摘要针对归档副本计算,以便日后检验交付文件
collect(payload);
files.sort((a, b) => a.path.localeCompare(b.path));
writeFileSync(join(staging, 'manifest.json'), JSON.stringify({
  version, platform, channel, runId, creatorVersion, commit, files,
}, null, 2) + '\n');
renameSync(staging, target); // 同一文件系统内完成最终批次发布
console.log(`已归档 ${files.length} 个文件:${target}`);

例如在 macOS 或 Linux 的 shell 中执行;3.8.0 和 ci-0042 仅是演示值,应替换为当前环境的真实版本及唯一批次号。

bash
COCOS_CREATOR_VERSION=3.8.0 node archive.mjs build/web-mobile 1.4.0 web-mobile official ci-0042

预期输出(文件数量取决于实际构建内容):

text
已归档 <COUNT> 个文件:release-archive/1.4.0/web-mobile/official/ci-0042

脚本先写入 .staging 临时目录,清单完成后才将其更名为正式批次;如果正式批次已存在,就报错而不覆盖。manifest.json 的 files 数组保存每个相对路径及其 SHA-256,上传制品仓库时应把整个批次目录一起上传。

让归档真正支持回溯

当某个渠道出现问题,先由发布记录定位 版本 + 平台 + 渠道 + 批次,再核对下载文件的 SHA-256 是否与清单一致。若摘要不符,应先排查上传、CDN 或人工替换;一致时再用记录的 Git commit 和构建配置重现问题,避免在错误的源码版本上调试。

除了脚本生成的清单,还应留存构建选项导出文件、依赖锁文件、CI 日志、原生 SDK/NDK/JDK 或 Xcode 版本以及适用的符号文件。源码和配置要能与批次对应,归档权限宜设为只读并规定保留期限。签名密钥、口令和渠道访问令牌不得放入普通制品仓库,只记录可公开的证书标识或签名指纹。

归档做对的验收标准是:能凭一条发布记录找到唯一批次,清单覆盖全部交付文件,历史批次不会被新构建覆盖,并且不接触签名密钥也能定位对应源码和构建条件。

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

目录与阅读设置

阅读设置

17

记录一个想法

发布产物怎样归档和追溯

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

登录哪都通