游戏引擎 / 系统课时
构建小游戏平台版本
构建小游戏平台版本
游戏在 Cocos Creator 编辑器内能够运行,并不代表已经具备小游戏平台的发布条件。本课使用 Cocos Creator 3.8 的微信小游戏平台作为实例,完成构建参数检查、平台产物生成、开发工具预览和基本验收,同时区分构建成功、真机运行成功与正式发布三个不同阶段。
学习目标
- 理解小游戏构建任务需要的目标平台、启动场景和平台配置。
- 完成微信小游戏构建,并识别生成目录中的关键文件。
- 使用平台开发工具验证构建产物,定位常见构建与运行问题。
确认发布前提
Cocos Creator 支持多个小游戏平台,但不同平台使用的运行环境、配置文件、开发工具和审核流程并不完全相同。不能把 Web Mobile 的构建目录直接当成微信或抖音小游戏发布包,也不能假设换一个文件夹名称就完成了平台转换。
本次选择微信小游戏作为具体操作目标。开始之前应确认以下条件:
- 项目能够在 Cocos Creator 3.8 编辑器中正常预览,启动场景已经保存。
- 所有正式运行需要的场景、脚本和资源均已纳入项目,关键资源不存在缺失引用。
- 本机已经安装微信开发者工具,并能够正常打开。
- 已准备微信小游戏 AppID;正式发布必须使用对应小游戏的有效 AppID 和具备权限的账号。
- 已确认游戏方向,例如竖屏项目使用
portrait,并与上一课的界面布局保持一致。
可以在 Cocos Creator 的「文件 → 偏好设置 → 原生开发环境」中配置微信开发者工具路径。具体菜单名称可能随编辑器系统语言略有差异,应以 Cocos Creator 3.8 实际界面为准。
配置并执行构建
打开菜单「项目 → 构建发布」,新建构建任务或选择已有任务。在平台列表中选择微信小游戏,然后按照项目实际情况填写设置。

以竖屏小游戏为例,重点检查以下配置:
| 构建项目 | 示例或要求 | 检查目的 |
|---|---|---|
| Platform | 微信小游戏 | 确保使用目标平台适配层 |
| Start Scene | 游戏入口场景 | 避免运行后进入错误场景 |
| AppID | 当前小游戏有效 AppID | 确认项目与平台账号对应 |
| Orientation | portrait | 与竖屏布局保持一致 |
| Build Path | 当前构建任务指定目录 | 确认可交付产物的位置 |
| Start Scene Asset Bundle | 按实际加载需求选择 | 决定启动场景资源的组织方式 |
完成检查后点击「构建」,等待任务结束。构建期间观察编辑器控制台和构建任务日志,不要仅根据输出文件夹已经出现就认定构建成功。
对于初次发布的小项目,建议先采用简单的本地资源组织方案,把核心玩法跑通后再评估远程资源、分包或引擎插件等优化功能。没有准备好实际资源服务器时,不要随意开启依赖远程地址的资源配置。
阅读与校验构建产物
Cocos Creator 会把项目的场景、脚本和资源处理为目标平台能够加载的结构。以默认名称的微信小游戏构建任务为例,输出通常位于项目的 build/wechatgame 目录;实际路径应以构建任务显示的输出位置为准。
微信小游戏构建产物中的两个重要配置文件是:
game.json:小游戏运行环境配置,包含设备方向等平台信息。project.config.json:微信开发者工具的项目配置,包含 AppID 等信息。
其他脚本与资源目录会随构建选项和项目内容变化,不应依赖某个固定目录层级作为所有版本的统一结构。

为了避免交付时拿错构建目录,可以通过简单的 Node.js 脚本检查关键配置文件。下面的脚本不修改构建产物,只验证 JSON 可以读取、设备方向为竖屏,并且 AppID 字段已经填写。
在项目根目录创建 verify-wechat-build.js:
const fs = require('node:fs');
const path = require('node:path');
const dir = process.argv[2];
if (!dir) throw new Error('请传入构建输出目录');
// 读取目标平台生成的配置,而不是源项目设置
const game = JSON.parse(
fs.readFileSync(path.join(dir, 'game.json'), 'utf8')
);
const project = JSON.parse(
fs.readFileSync(path.join(dir, 'project.config.json'), 'utf8')
);
// 本次示例约定项目采用竖屏构建
if (game.deviceOrientation !== 'portrait') {
throw new Error('设备方向不是 portrait');
}
if (typeof project.appid !== 'string' || !project.appid.trim()) {
throw new Error('AppID 未配置');
}
console.log('方向: portrait');
console.log('AppID: 已配置');确保本机安装了 Node.js,在终端执行:
node verify-wechat-build.js "<PATH>"其中 <PATH> 需要替换为实际构建目录,例如默认任务对应的 build/wechatgame。若目录位置、任务名称或文件内容不同,应以本次构建的实际产物为准。
预期输出(文件存在、格式正确且满足上述检查条件时):
方向: portrait
AppID: 已配置如果文件不存在、JSON 无法解析或配置不符合条件,脚本会抛出错误,不能视为检查通过。这里仅核对了文件结构和基本字段,无法验证 AppID 的真实有效性、包体限制或平台权限,因此仍需要在微信开发者工具中继续检查。
在平台工具中预览验收
构建成功只是得到目标平台代码包,真正运行还需要平台开发工具和对应运行环境。微信小游戏运行环境并不完全等同于普通浏览器,因此浏览器预览通过的功能仍可能在小游戏平台上出现差异。
按照以下顺序完成验证:
- 在 Cocos Creator 构建发布面板中选择对应任务,使用「运行」或相关入口打开微信开发者工具;也可以手动导入生成的小游戏项目目录。
- 在开发者工具中确认项目类型、AppID 和入口文件能够正常识别。
- 启动模拟器,检查首屏、场景切换、图片资源、按钮响应及声音行为。
- 打开开发者工具的控制台,检查资源加载、脚本执行和平台接口错误。
- 使用具备权限的账号进行预览或真机调试,在真实手机上检查触控、安全区、运行速度和网络资源加载。
- 检查包体大小、平台要求及发布配置,在满足条件后再进入上传、体验、审核流程。
如果项目使用远程 Asset Bundle,需要确认对应资源已经部署到正确的服务器位置,访问地址、HTTPS 和平台允许的网络域名配置均符合要求。仅在构建面板中填写远程地址不会自动完成服务器部署。
建议准备一份最小验收记录,至少包含目标平台、构建任务名称、测试设备、首次启动结果、操作按钮是否正常、主要资源是否加载成功和未解决问题。这样在后续重新构建时,可以确认修复是否真正进入了新版本。
处理常见构建与运行问题
实际发布中,问题通常分布在构建配置、平台工具和运行时资源三个阶段。排查时应先确定错误发生在哪一层,而不是看到黑屏就直接重新打包。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 构建任务失败 | 构建日志、脚本错误、资源引用 | 修复首个明确错误,再重新构建 |
| 无法打开微信开发者工具 | 工具安装路径、工具版本 | 修正路径,必要时手动导入项目 |
| 提示 AppID 或权限异常 | 项目配置、账号权限 | 使用正确 AppID 和授权账号 |
| 启动后黑屏 | 启动场景、控制台、资源加载 | 确认场景与关键资源实际进入产物 |
| 模拟器正常、真机资源缺失 | 远程地址、域名、网络与缓存 | 检查平台网络限制和资源部署 |
| 按钮显示正常但无法操作 | 安全区、UITransform、事件拦截 | 回到触控与布局层定位问题 |
最后需要明确三个验收边界:构建通过表示生成任务完成,运行通过表示产物在目标环境中能够正确执行,发布通过表示符合平台提交、权限与审核要求。只有这三个阶段分别验证完成,小游戏才真正具备交付条件。