游戏引擎 / 系统课时
版本号怎样贯穿一次发布
版本号怎样贯穿一次发布
同一款 Cocos Creator 游戏会同时产出 Web 页面、小游戏和原生安装包。只在包名上写版本,很容易出现包体已经更新、远程资源却仍是旧版的问题。本课建立统一的发布编号与记录,让构建、部署、验收和回滚都能定位到同一批产物。
学习目标
- 区分应用版本、构建号、资源版本与发布标识的职责。
- 用同一份发布参数为不同平台生成可追溯记录。
- 检查包体、远程资源和线上发布记录是否匹配。
先给四种版本字段定职责
| 字段 | 示例 | 用途 |
|---|---|---|
appVersion |
1.8.0 |
面向玩家的功能版本;映射到商店所需的展示版本 |
buildNumber |
2087 |
区分同一应用版本的不同构建;按平台规则映射到内部构建号 |
resourceVersion |
res-2087 |
标识本次发布所使用的远程资源集合 |
releaseId |
1.8.0+2087 |
串联流水线、各平台产物、部署与回滚记录 |
另存 commit 和 platform,才能知道版本由哪个源码提交生成、落到了哪个渠道。Android 的 versionName/versionCode、iOS 的 CFBundleShortVersionString/CFBundleVersion 需要在各自的打包配置中设置;上表只是项目约定,不是 Creator 会自动写入安装包的内置字段。
让一次发布只有一个版本来源
发布流水线先锁定源码提交并确定发布规格,再把字段分别送往各平台构建配置、远程资源目录和发布记录。同一发布不允许某个平台自行重新计算资源版本。需要单独递增原生构建号时,保留共同的 releaseId,另外记录平台构建号。

Cocos Creator 3.8 的 md5Cache 可以让构建资源使用内容哈希以辅助缓存更新,但这些哈希不是人为管理的 resourceVersion。远程 Asset Bundle 要按项目约定发布到对应版本位置,并检查客户端引用的 Bundle 是否与该位置兼容。
生成可以复核的发布清单
下面使用 Node.js 18+。在项目根目录创建 scripts/emit-release.mjs;脚本只生成自定义发布记录,不会替你修改原生平台的版本设置。
import { mkdirSync, writeFileSync } from 'node:fs';
const [platform, appVersion, numText, resourceVersion, commit] =
process.argv.slice(2);
const buildNumber = Number(numText);
// 拒绝空字段和非法平台名,防止生成不可靠的发布文件。
if (!/^[a-z0-9-]+$/.test(platform ?? '') ||
!/^\d+\.\d+\.\d+$/.test(appVersion ?? '') ||
!Number.isSafeInteger(buildNumber) || buildNumber <= 0 ||
!resourceVersion || !/^[0-9a-f]{7,40}$/i.test(commit ?? '')) {
console.error('发布参数不合法');
process.exit(1);
}
const release = {
releaseId: `${appVersion}+${buildNumber}`,
platform, appVersion, buildNumber, resourceVersion, commit
};
mkdirSync('release-records', { recursive: true });
writeFileSync(
`release-records/${platform}.json`,
JSON.stringify(release, null, 2) + '\n'
);
console.log(`已记录 ${release.releaseId} ${platform} ${resourceVersion}`);执行一次 Web Mobile 发布记录生成:
node scripts/emit-release.mjs web-mobile 1.8.0 2087 res-2087 a1b2c3d预期输出:
已记录 1.8.0+2087 web-mobile res-2087预期结果:release-records/web-mobile.json 含五个输入字段及 releaseId,可随制品归档。实际构建时,流水线应从同一份锁定的发布规格读取参数,而不是为每个平台手工填写不同的值。
发布前怎样验收与回滚
- 构建后读取 Android、iOS 的真实包版本,核对它们与发布记录中的映射关系;Web、小游戏核对上传的产物版本和渠道记录。
- 检查本次远程资源的目录或清单是否存在,验证下载地址、资源内容和客户端兼容范围;不能只检查构建成功日志。
- 在发布系统记录
releaseId、提交号、各平台产物位置与校验值、资源版本和部署环境。先小范围验证,再扩大投放。
若线上出现“新包加载旧资源”,先根据客户端实际运行的 releaseId 查包体,再追踪它所引用的资源版本和 CDN 缓存。回滚时应恢复彼此兼容的包体与资源组合,不能只把应用显示版本改回去。