微信运行时与平台适配边界
适用:原理引擎无关,示例目标 Cocos Creator 3.8.8 + TypeScript。资料核查:2026-11-17。Cocos 官方资料为 3.8 LTS 文档;已核对微信官方运行环境资料,并用官方源码交叉确认接口形态;本项目构建证据见统一验证报告,未进行真机实测。
先把 JavaScript 与浏览器分开
小游戏能运行 JavaScript,不意味着拥有完整网页环境。浏览器里的 DOM、页面导航、CSS 布局和现成网页组件,不能直接推导为小游戏可用能力。微信通过自己的运行时暴露渲染、输入、网络、存储与平台接口,游戏引擎再做一层适配。学习这层边界,可以解释为什么本地网页已经能玩,构建后却在启动时因 document 或某个浏览器库报错。
Cocos 项目的节点、精灵和动画通常通过引擎适配层落到目标平台,业务不需要自己重新创建主画布。直接把网页教程里的 canvas 初始化复制进游戏,可能与引擎争夺画布、输入或渲染上下文。只有做特定底层能力时才直接调用平台对象,并检查其所有权。微信官方示例展示了直接创建画布的模式;它说明原生 API 如何使用,不代表应该嵌进已管理画布的 Cocos 场景。
一次调用经过哪些层
将一次“点击复活”拆开看:Cocos 输入事件触发应用流程,流程通过平台适配器请求广告,适配器处理 wx 对象与回调,再把规范化结果返回业务,业务决定是否请求服务端复活,最后更新场景。任何一层直接越过其他层都容易制造隐藏依赖,例如按钮组件直接改背包、广告回调直接切场景、平台错误直接穿透为无意义的空白提示。
type RewardedResult =
| { kind: 'completed' }
| { kind: 'cancelled' }
| { kind: 'unavailable'; reason: string };
interface GamePlatform {
readonly name: 'browser' | 'wechat';
showRewarded(): Promise<RewardedResult>;
onVisibility(fn: (visible: boolean) => void): () => void;
now(): number;
}
接口只暴露游戏需要的能力,不把整个 wx 命名空间转发出去。浏览器替身可以返回取消、成功或不可用,用于测试业务时序;正式微信实现才引用 wx 类型。这样既不要求把游戏写成大型抽象框架,也能避免每个组件散落 if (typeof wx)。适配器是一条稳定的依赖边界,不是为了假装所有平台完全相同。
能力探测与降级必须有产品含义
同为微信小游戏,不同宿主、系统、客户端版本、基础库和账号条件仍可能影响能力。某个函数存在,只能说明入口存在,不能保证调用成功或账号已开通。用运行时检测保护调用,再用成功、失败与取消结果驱动流程。不要把编译期类型通过当成运行时兼容证明,也不要仅凭系统名就推断某项能力必然可用。
降级应在需求阶段决定。广告不可用时可以允许退出复活选择,或按已批准规则提供其他途径;排行榜不可用时显示普通个人成绩;非关键震动失败可以静默跳过。支付不可用则应清楚展示当前不能购买,不能伪造成功。把未知错误统一吞掉并继续主流程,往往比明确失败更难诊断。
npm 库需要检查运行时依赖
选择 TypeScript 库时,先读它是否依赖 DOM、Node 内置模块、动态代码生成、原生插件或不可用网络接口。纯数学、数据结构与规则模块通常更容易复用;网页 UI 和依赖 Node 文件系统的工具不应直接放入客户端运行。构建工具的 Node 环境与游戏运行时是两回事,开发时成功 import 也可能只是没有执行到有问题的路径。
先用一个最小场景验证第三方库的关键调用,再引入整套玩法。资源路径、模块打包与初始化副作用需要一起检查。若库只为一个简单需求服务,使用语言或引擎已有能力往往更容易跨端验证。必要的兼容补丁集中在适配层,并记录适用版本,避免在业务代码中复制多个略有差异的全局对象替身。
坐标与像素也是平台边界
窗口逻辑尺寸、设备像素比和引擎设计分辨率并非同一概念。直接把触摸坐标乘设备像素比,再传给已经完成映射的 Cocos UI,会产生双重缩放。先确定输入来源属于屏幕、UI 还是世界坐标,经过明确转换后再做命中判断。画布实际分辨率决定渲染成本,界面布局尺寸决定内容如何摆放,不能用一个数字同时处理二者。
平台覆盖式界面可能显示在引擎画面之上,游戏输入需要相应暂停或屏蔽;这类界面通常不属于节点树,不能期待引擎遮罩自动裁剪它。音频、键盘、分享等能力也有独立生命周期。资源和接口的销毁责任应由创建者或明确的上层所有者承担,页面切换时不能只销毁节点而遗留平台对象。
排查“网页可以、微信不行”
先拿最早的错误和调用栈,定位它发生在适配加载前、引擎启动、场景加载还是业务调用。再比较两个目标实际加载的脚本与资源,不要用不同版本的产物做比较。缺失全局对象通常是依赖问题;路径错误常来自构建后目录改变;平台接口失败则需要核对账号、权限、域名与能力条件。一次改多个兼容开关会使因果关系消失。
建立三列证据:浏览器替身通过了什么、微信开发者工具通过了什么、真机通过了什么。测试报告不能把模拟广告成功写成广告接入成功。平台运行时的课程知识能缩小排查范围,但任何具体机型表现仍要由真实构建与现场证据支持。
交给 AI 的任务与验收
可复制任务:“为 Cocos 3.8.8 游戏建立最小平台适配器,只包含可见性和激励广告结果。浏览器提供可切换替身,微信实现集中引用 wx;业务组件不访问 wx。列出第三方依赖中的 DOM/Node 假设,设计不可用能力的界面行为。”
验收搜索业务目录不出现散落 wx 调用;浏览器能分别演示完成、取消、不可用;切场景后监听数量回到基线;错误能定位阶段。微信能力是否真实可用,留到开发者工具与真机以实际包验证。
官方来源
-
Cocos 3.8 发布到微信小游戏:运行环境与引擎适配边界。
-
微信官方 Canvas 类型测试:原生画布与输入调用形态。
-
微信官方小游戏示例入口:直接初始化与平台调用的源码例子;示例依赖与参数不视为本课程推荐的当前默认配置。
-
微信运行环境原文:2026-11-17已读取,部分工具实现描述有历史性,实际开发者工具产品版本以现场安装为准。