游戏引擎 / 系统课时
构建参数怎样脱离源码管理
构建参数怎样脱离源码管理
测试服地址、渠道标识和发布开关如果散落在游戏脚本里,每切一次环境都要改代码、重新审查,甚至可能把测试地址带进正式包。本课把参数放进独立配置,构建前统一校验与注入,让同一份业务代码可以生成不同环境的产物。
学习目标
- 将 Creator 构建选项、游戏运行时配置与敏感凭据分开管理。
- 通过环境配置生成可复用的构建参数和运行时 JSON 资源。
- 验证切换环境后产物行为发生变化,而业务源码保持不变。
哪些参数应该放在哪里
| 参数类别 | 示例 | 推荐位置 |
|---|---|---|
| Creator 构建选项 | platform、debug、md5Cache |
构建面板导出的配置或 CI 构建参数 |
| 游戏环境配置 | API 基础地址、渠道、诊断开关 | 可审查的环境配置文件,构建时注入资源 |
| 私密凭据 | 签名口令、上传令牌 | CI 的密钥管理系统,不进仓库或客户端 |
“脱离源码”不是把全部配置都藏起来:非敏感的环境配置可以提交到 Git,以便复核变更;密钥则应在构建或部署环节由 CI 注入。客户端可以读到随包发布的 URL 和开关,因此不要用运行时 JSON 存放真正的秘密。
从环境配置生成构建输入
先创建 config/profiles/staging.json。此处以 Web Mobile 为例,地址为演示用测试域名,不代表真实后端。
json
{
"platform": "web-mobile",
"debug": false,
"md5Cache": true,
"apiBaseUrl": "https://api.staging.example.test",
"channel": "qa",
"enableDiagnostics": true
}创建 scripts/prepare-env.mjs。它会检查字段,把属于游戏运行时的配置写到 resources 目录,同时打印 Cocos Creator 3.8 已支持的命令行构建选项。
js
import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
const env = process.argv[2];
if (!['staging', 'production'].includes(env)) {
console.error('环境仅支持 staging 或 production');
process.exit(1);
}
const cfg = JSON.parse(readFileSync(
join('config', 'profiles', `${env}.json`), 'utf8'
));
// 在调用 Creator 之前验证环境字段,避免构建后才发现地址为空。
if (cfg.platform !== 'web-mobile' ||
typeof cfg.debug !== 'boolean' ||
typeof cfg.md5Cache !== 'boolean' ||
!/^https:\/\//.test(cfg.apiBaseUrl ?? '') ||
!cfg.channel || typeof cfg.enableDiagnostics !== 'boolean') {
console.error('环境配置字段不合法');
process.exit(1);
}
const output = 'assets/resources/config/build-env.json';
mkdirSync('assets/resources/config', { recursive: true });
writeFileSync(output, JSON.stringify({
apiBaseUrl: cfg.apiBaseUrl,
channel: cfg.channel,
enableDiagnostics: cfg.enableDiagnostics
}, null, 2) + '\n');
console.log(
`构建参数: platform=${cfg.platform};debug=${cfg.debug};md5Cache=${cfg.md5Cache}`
);
console.log(`资源配置: ${output}`);在项目根目录执行:
bash
node scripts/prepare-env.mjs staging预期输出:
text
构建参数: platform=web-mobile;debug=false;md5Cache=true
资源配置: assets/resources/config/build-env.json预期结果:生成的 JSON 包含三个运行时字段,且不包含构建选项和秘密。再准备 config/profiles/production.json 并切换参数,即可生成不同环境配置,脚本本身不用修改。
把参数真正送进 Cocos 构建

- 在启动 Creator 构建前运行准备脚本,使编辑器资源数据库能够导入
assets/resources/config/build-env.json。为该资源保留稳定的.meta,不要反复删除并生成新的 UUID。 - 调用 Cocos Creator 3.8 可执行程序,传入项目的
--project路径,以及脚本打印出的--build "platform=web-mobile;debug=false;md5Cache=true"。实际可执行程序位置因系统与安装路径而异。 - 其他平台不要生搬 Web 参数:在构建发布面板配置目标平台、导出构建配置,再按该平台插件实际支持的字段维护配置;使用
--build的configPath可读取导出的 JSON。
游戏端可通过 Cocos Creator 的 JsonAsset 加载该资源。以下是挂在场景节点上的完整组件,适合验证生成的文件是否真的进入包内。
ts
import { _decorator, Component, JsonAsset, resources } from 'cc';
const { ccclass } = _decorator;
@ccclass('BuildEnvReader')
export class BuildEnvReader extends Component {
start() {
// 路径相对 assets/resources,加载时不写 .json 扩展名。
resources.load('config/build-env', JsonAsset, (err, asset) => {
if (err || !asset) {
console.error('环境配置加载失败', err);
return;
}
const config = asset.json as {
apiBaseUrl: string;
channel: string;
enableDiagnostics: boolean;
};
console.log(
`ENV ${config.channel} ${config.apiBaseUrl} diagnostics=${config.enableDiagnostics}`
);
});
}
}在已挂载该组件的测试场景运行、成功加载资源后,预期输出:
text
ENV qa https://api.staging.example.test diagnostics=true防止测试参数和密钥混入正式包
构建检查至少要核对:正式包的 apiBaseUrl 指向生产环境、渠道与发布记录一致、debug 符合发布策略、诊断开关按要求关闭。若修改了环境文件却未重新导入资源,可能出现“控制台参数正确,包内仍是旧配置”,此时应检查准备脚本执行时机与最终包内的资源内容。
按自己的节奏,确认真正理解。