游戏引擎 / 系统课时

构建参数怎样脱离源码管理

构建参数怎样脱离源码管理

测试服地址、渠道标识和发布开关如果散落在游戏脚本里,每切一次环境都要改代码、重新审查,甚至可能把测试地址带进正式包。本课把参数放进独立配置,构建前统一校验与注入,让同一份业务代码可以生成不同环境的产物。

学习目标

  • 将 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 构建选项与运行时资源

  1. 在启动 Creator 构建前运行准备脚本,使编辑器资源数据库能够导入 assets/resources/config/build-env.json。为该资源保留稳定的 .meta,不要反复删除并生成新的 UUID。
  2. 调用 Cocos Creator 3.8 可执行程序,传入项目的 --project 路径,以及脚本打印出的 --build "platform=web-mobile;debug=false;md5Cache=true"。实际可执行程序位置因系统与安装路径而异。
  3. 其他平台不要生搬 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 符合发布策略、诊断开关按要求关闭。若修改了环境文件却未重新导入资源,可能出现“控制台参数正确,包内仍是旧配置”,此时应检查准备脚本执行时机与最终包内的资源内容。

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

目录与阅读设置

阅读设置

17

记录一个想法

构建参数怎样脱离源码管理

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

登录哪都通