游戏引擎 / 系统课时

真机启动异常先查哪一层

真机启动异常先查哪一层

Cocos Creator 3.8 小游戏在编辑器里能预览,换成微信真机却黑屏、卡在加载页或启动即退出时,盲目改场景脚本往往无效。本课按构建产物、平台配置、资源加载、运行日志四层检查,先确定故障发生在游戏启动链路的哪一步。

学习目标

  • 根据启动停留阶段选择最先检查的证据。
  • 使用脚本快速检查微信小游戏构建目录与配置文件。
  • 区分平台配置、远程资源与运行时脚本异常,并完成真机复验。

按启动链路缩小范围

小游戏不是直接运行编辑器场景。发布包必须先被平台工具识别,随后平台初始化运行环境,引擎再装载脚本和资源,最后才进入首场景。前一层失败时,后一层的日志可能根本不会出现。

微信小游戏真机启动失败的四层排查流程

先复现一次冷启动,记下机型、系统、微信版本、网络环境、构建任务和首个报错。若开发者工具连项目都无法正常导入,优先看产物;能进入加载页却资源请求失败,看资源层;界面渲染了一半才报异常,通常应从首个 JavaScript 错误及其调用栈入手。

检查发布包而不是源码目录

在 Creator 的“项目 → 构建发布”选择微信小游戏,重新构建后通过任务面板打开实际发布目录。目录名以构建任务为准,不要假定始终叫 build/wechatgame。微信小游戏产物应包含入口 game.js 及 game.json、project.config.json;其中 project.config.json 用于开发者工具工程配置,game.json 承载小游戏运行配置。

下面使用 Node.js 18 或更新版本检查文件与 JSON 语法。将脚本保存为 check-wechat-package.mjs:

js
import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';

const root = process.argv[2];
if (!root) {
  console.error('Usage: node check-wechat-package.mjs <PATH>');
  process.exit(1);
}

for (const name of ['game.js', 'game.json', 'project.config.json']) {
  if (!existsSync(join(root, name))) {
    throw new Error(`missing: ${name}`);
  }
  console.log(`OK ${name}`);
}

JSON.parse(readFileSync(join(root, 'game.json'), 'utf8'));
const project = JSON.parse(
  readFileSync(join(root, 'project.config.json'), 'utf8')
);
if (typeof project.appid !== 'string' || project.appid.length === 0) {
  throw new Error('missing: appid');
}
console.log('OK manifest JSON and AppID field');

在终端运行,<PATH> 替换为实际的微信小游戏发布目录,路径可能因项目不同而变化:

bash
node check-wechat-package.mjs "<PATH>"

预期输出(文件完整且配置字段存在时):

text
OK game.js
OK game.json
OK project.config.json
OK manifest JSON and AppID field

这只能证明基本文件与配置格式存在,不能证明 AppID 属于当前小游戏,也不能证明代码能在真机运行。若出现 missing,先确认选对平台和发布目录再重新构建,不要直接在生成目录里补造文件。

核对渠道配置和资源位置

用微信开发者工具导入上一步确认的产物目录,检查工程 AppID 是否与微信公众平台登记的小游戏一致、测试账号是否具备预览权限,以及 game.json 中的方向等选项是否符合预期。基础库与真机微信版本的兼容性也应记录;开发者工具模拟器通过,不代表手机一定支持相同能力。

如果包能启动但停在加载界面,优先核对资源是否在包内、分包还是远端。Cocos Creator 3.8 的微信小游戏发布流程允许设置远端资源;配置了资源服务器地址,还需确保对应资源确实已上传。远端资源请求应检查 HTTPS、合法域名、路径大小写、服务器响应、证书及权限。包体限制和分包配置按当前微信平台规则与 Creator 3.8 发布文档 核对,不能依靠开发者工具的宽松调试选项代替真机验证。

从首个异常定位到具体脚本

打开微信开发者工具的 Console、Network 等调试视图,并使用真机调试能力查看设备侧日志。最重要的是找第一个异常,而不是只看最后的“启动失败”提示。404 或域名拦截属于下载链路,模块加载失败先检查构建脚本和分包,TypeError 则结合调用栈定位具体脚本与平台 API 使用时机。

若首场景可以进入,可临时在首场景组件 onLoad 和 start 加入不同的 console.info 标记。只看到 onLoad,说明问题发生在该组件启动前后的链路中;两个标记都出现,也不能单凭它们断言首帧已渲染。若一个标记都没有,先排查入口、引擎初始化和场景资源,不要反复修改按钮逻辑。

用同一台设备验证修复

每次只修改一层:例如修正 AppID、重新上传远端资源,或修复第一处脚本异常。重新构建并在相同真机、相同网络下冷启动,对比最初的失败日志是否消失;再测试首次安装、清缓存后启动和普通二次启动。最终验收不是“没有红字”,而是首场景正常渲染、交互可用,且不再依赖开发者工具的特殊放宽设置。

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

目录与阅读设置

阅读设置

17

记录一个想法

真机启动异常先查哪一层

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

登录哪都通