测试全绿进Cocos就白屏：微信小游戏AI开发踩坑实录与修复方案

测试全绿结果一进Cocos场景就白屏。控制台第一行报错是TypeError: Cannot read property xxx of undefined我盯着屏幕看了十几秒脑子里只有一个念头AI生成的测试代码明明全部通过了为什么到真环境里就成了废纸这篇文章就用项目《清单之外》复盘一下这个典型问题。这是一款微信小游戏玩法类似“每日挑战清单”——每天给你一组稀奇古怪的小任务比如“拍一张云的照片”“给五年后的自己写一句话”做完一样划掉一样核心逻辑是任务生成、进度持久化、完成判定与奖励解锁。开发过程中我把核心逻辑交给了AI辅助生成单元测试跑得漂亮十几个用例全绿结果一进Cocos Creator就翻车而且翻车得特别“经典”——不是语法错误不是业务逻辑错而是代码在微信小游戏环境里根本没跑起来。这篇文章适合正在用AI辅助做游戏开发、尤其是往微信小游戏平台交付的同学。我会把这次从“测试全绿”到“进引擎失败”的完整排查链路、背后的根源分析、以及修复后的通用解法一条一条拆开讲你能直接照着这套思路去查自己的项目。1. 项目全貌与整体设计思路1.1 《清单之外》玩法与项目结构《清单之外》的设定很简单游戏内置一份“人生挑战清单”用户可以每日打卡完成任务。核心模块拆成三块任务池管理生成当天的挑战列表、进度与状态管理记录完成情况、连续打卡天数、奖励系统根据完成数量解锁称号。AI辅助开发的分工是这样的我本人负责项目骨架、Cocos场景搭建和素材导入AI负责生成三块核心业务逻辑的TypeScript代码同时配套生成单元测试。代码量不大核心三个文件加起来大概一千多行测试文件三百多行。技术选型方面客户端使用Cocos Creator 3.8发布目标是微信小游戏。逻辑代码全部用TypeScript写在assets/scripts/目录下不能依赖任何Cocos内置组件为了测试方便也就是说所有业务逻辑里不直接import cc组件只通过接口与表现层交互。这套设计本身是合理的把业务逻辑跟引擎解耦逻辑层可以脱离Cocos用Node环境跑测试。AI生成的代码也确实遵守了这条规则单元测试全部通过了。问题恰恰出在这个“脱离引擎”的边界上——AI用Node环境模拟了所有引擎之外的东西但它模拟不了引擎与微信环境本身。1.2 AI辅助开发的任务拆解我给AI的提示词使用了“四个子任务”拆分法任务池算法根据日期生成一组固定数量的挑战项要求同一天重复打开游戏拿到的是同一组任务进度存储使用微信小游戏的storage接口封装读写带版本号与迁移逻辑完成判定点击完成时校验当前任务状态、连续打卡天数、奖励解锁条件测试文件对以上三个模块分别编写vitest单元测试覆盖正常流程与边界情况。AI生成结果非常理想测试用例里什么“连续打卡断了之后重新累计”“同一天不能重复获取新任务”这些边界条件全部覆盖到了。跑测试时npm run test输出一片绿色我当时信心很足直接往Cocos里拖Component绑定数据然后点预览——白屏。这个翻车过程值得复盘因为“测试全绿”本身没有错错的是我把测试环境的“全绿”当成了“整个系统全绿”。2. 测试全绿为什么这么有欺骗性2.1 AI生成测试的三个典型陷阱先说结论AI生成代码的测试全绿不代表代码能跑。它一定是在某个前提下建立的验证而这个前提在你的目标环境里往往不成立。第一个陷阱mock替身掩盖真实依赖缺失。AI在测试文件里为了隔离环境通常会mock掉storage、wx API、全局对象等。比如测试进度存储时AI写了一个fakeStorage的替身实现所有的读写都发生在内存里。测试全绿只能证明“逻辑面对这个fakeStorage时是健壮的”证明不了“逻辑面对微信小游戏真实存储接口时能正常工作”。第二个陷阱测试运行环境差异。单元测试跑在Node进程里天然存在完整的globalThis、process、console甚至AI还顺手给测试环境注入了window和document的模拟实现。微信小游戏运行时本质是个阉割版JavaScript引擎window存在但很多浏览器API缺失。AI测试里用到的localStorage、XMLHttpRequest、URL.createObjectURL之类的对象小游戏环境里要么不存在要么只有替代品。第三个陷阱生命周期错位。Cocos场景脚本有onLoad/start/update生命周期微信小游戏有onShow/onHide等App生命周期AI生成的纯逻辑类完全没有这个概念。测试时我直接new一个类调用方法全绿但Cocos里在onLoad阶段就调用了依赖渲染层的方法而此时场景节点还没准备好自然报错。2.2 我为测试全绿付出的代价说实话看到全绿的那一刻我犯了一个经验错误没有在“纯逻辑测试”和“引擎集成验证”之间设置一个过渡步骤。典型的验证链路应该是三层纯逻辑单元测试跑在Node里验证业务正确性引擎内运行验证跑在Cocos模拟器里验证生命周期与组件绑定真机预览验证跑在微信开发者工具或真机上验证平台API适配。我直接从第一层跳到了第三层中间那层省了结果失败成本全积压到了最后一步。现在回头看AI辅助开发最危险的点就是它把第一层验证做得极其完美让你忽略剩下两层。就像你让一个助手写数据分析报告他查了数据库里的数据算出了完美结论但你没让他看看数据库本身的连接是不是通的——一上线连接断了。3. 进Cocos后的失败场景全记录3.1 第一轮报错白屏与初始化失败在Cocos Creator里点击预览模拟器加载后直接白屏。打开控制台错误一大堆整理下来就两类ReferenceError和TypeError。其中最显眼的几个ReferenceError: window is not defined TypeError: Cannot read property getItem of undefined Error: Module cc is not found in the current environment TypeError: xxx is not a function这四条错误正好对应了四个不同层面的问题全局对象缺失、存储接口缺失、模块加载异常、API能力差异。由于错误堆积在一起我一度以为是Cocos配置错了后来一条一条往下剥才看出门道。3.2 七大失败原因逐条拆解把这次遇到的所有问题归拢了一下一共七个根源每一个单独拿出来都不复杂但合在一起足以让整个项目扑街。第一个根源Cocos模块加载机制不同。Cocos Creator对于脚本的打包有一套自己的模块系统它支持ES模块但模块路径解析规则严格。AI生成的代码里用了相对路径import这个没问题问题在于AI生成的文件里还有几条import语句引用了浏览器环境里的全局组件比如import { EventTarget } from cc。在Node环境跑测试时这个import会被AI的mock给拦截掉测试全绿但Cocos里直接引入真实的cc模块如果组件的生命周期设置不对引用链条就断了。第二个根源受限的全局对象。微信小游戏环境里window存在但不是浏览器环境里的window很多方法缺失。AI代码里有一段是读取URL参数处理分享逻辑的用了window.location.search而微信小游戏环境里根本没有location对象。这段代码在Node测试里通过了因为vitest提供了jsdom环境模拟了完整的window.location。第三个根源生命周期初始化时序错误。我拿到AI生成的类之后在onLoad里就new了业务类并调用初始化方法。但业务类的构造函数里访问了storage接口而微信小游戏的storage需要在App启动之后才能使用Cocos场景onLoad阶段App环境还没有完全准备好接口虽然存在但初始化状态不对。这个问题属于集成方的失误但AI生成的代码里没有做任何“延迟初始化”或“环境探测”的保护它假设外部一定已经在合适时机调用它了。第四个根源API能力差异。AI代码里使用了Array.prototype.at()、String.prototype.replaceAll()这类较新的JavaScript APIiOS低版本微信的基础库不支持真机上一跑就挂。测试环境的Node版本很新所有新API都支持自然全绿。第五个根源平台特有API缺失。AI生成storage封装时在测试里用的是localStorage替身但真正的代码里用的微信小游戏的wx.setStorageSync。在Cocos模拟器里wx对象不是所有方法都可用一些方法在开发者工具里可用真机不可用反之亦然。第六个根源资源加载路径问题。AI生成的代码里有静态文件引用在Node测试环境里根本不会加载这些文件因为逻辑层不碰它们全绿但进Cocos后资源需要打进包体并且要改成项目相对路径或远程资源地址。这个问题我当时没有遇到但一起排查的朋友碰到过是AI生成代码的常见坑。第七个根源场景脚本执行顺序。Cocos里多个脚本挂在同一个场景时脚本组件之间的执行顺序可能影响初始化。AI生成的单测是按顺序执行的但Cocos里组件生命周期是交错触发的A组件的start可能先于B组件的onLoad执行。如果A依赖B就会在真环境里偶现报错。3.3 用一张表看问题问题层面测试环境表现微信小游戏环境表现根因全局对象jsdom完整模拟window/documentwindow存在但location等缺失环境差异存储接口localStorage替身wx.setStorageSyncAPI差异模块导入mock拦截cc模块真实模块解析规则严格加载机制生命周期按函数调用顺序执行组件生命周期交错触发时序错位JS APINode 20全量支持低版本基础库不支持新语法语法兼容平台APINode环境无wx对象wx部分方法仅真机可用平台差异资源引用逻辑层完全不碰资源需要适配项目路径与包体路径差异4. 修复过程与通用解决方案4.1 第一步加环境探测与适配层修复的第一步不是改业务代码而是加一个环境探测模块。它的作用是在运行时判断当前代码跑在什么环境里然后返回对应环境的适配器实现。// Environment.ts export type RuntimeEnv node | cocos | wechat; export function detectRuntime(): RuntimeEnv { // 微信小游戏环境特有标记 if (typeof wx ! undefined wx.getSystemInfoSync) { return wechat; } // Cocos Creator环境通常能拿到 cc 全局对象 if (typeof cc ! undefined) { return cocos; } return node; } export function getStorage(): StorageAdapter { const env detectRuntime(); switch (env) { case wechat: return new WechatStorageAdapter(); case cocos: return new LocalStorageAdapter(); default: return new MemoryStorageAdapter(); } }适配层的作用是隔离平台差异让业务代码永远只依赖一个统一的存储接口而不是直接操作wx或localStorage。这段代码看起来简单但它是把“Node测试全绿”翻译成“真机可运行”的核心桥梁。4.2 第二步延迟初始化与生命周期解耦把所有业务类的初始化方法从构造函数里挪出来改成显式的init()调用。在Cocos里不在onLoad里调用而是放到start里微信环境里在wx.onShow回调之后再调用。import { _decorator, Component } from cc; import { GameManager } from ./GameManager; const { ccclass } _decorator; ccclass(GameBootstrap) export class GameBootstrap extends Component { private game!: GameManager; protected start(): void { // 延迟到start再初始化确保Cocos生命周期和微信环境都已准备 this.game new GameManager(); this.game.init(); } protected onDestroy(): void { if (this.game) { this.game.dispose(); } } }之所以要延迟到start而不是onLoad是因为Cocos里onLoad阶段不能保证所有资源加载完成而start在所有组件初始化后的第一帧之前执行环境更稳定。这算是经验之谈踩过的坑多了就自然这么写了。4.3 第三步替换API并降级新语法AI代码里凡是用了window.location、window.navigator这类对象的地方全部改成通过适配层获取。微信小游戏有额外的全局对象可以拿到平台信息function getPlatformInfo(): PlatformInfo { if (detectRuntime() wechat) { const info wx.getSystemInfoSync(); return { platform: info.platform, language: info.language, version: info.version, }; } // 浏览器环境 return { platform: web, language: navigator.language, version: unknown, }; }新语法降级方面用TypeScript的编译target解决一部分。在项目tsconfig.json里把target设为es2017这样Array.prototype.at()、String.prototype.replaceAll()这些新API会在编译期被降级或报错提示逼着我把代码改成兼容写法。但注意Cocos自身可能有一些需要保留的配置不要整个改掉只针对逻辑代码。4.4 第四步重写测试策略三层验证修复完成后我重新设计了测试策略第一层纯逻辑测试沿用原来的vitest用例但额外增加一条环境断言明确检查当前代码是否依赖了不该出现的全局对象// 在测试入口加一个环境一致性检查 describe(environment validity, () { it(should not rely on browser-specific globals, () { const code readFileSync(src/GameManager.ts, utf-8); const disallowed [window.location, document., XMLHttpRequest]; for (const pattern of disallowed) { expect(code).not.toContain(pattern); } }); });第二层Cocos引擎内验证。这一步不能省我把代码接好之后在Cocos Creator的模拟器里跑一遍完整流程检查生命周期报错、模块路径、组件绑定这些Node测试覆盖不到的部分。第三层微信开发者工具里跑真机调试重点看存储接口和平台API在真实环境的表现。这三层全绿才算真正全绿。4.5 修完之后的运行验证修复后项目成功跑起来了任务生成、打卡完成、奖励解锁全部正常。但我特意做了一次破坏性测试把适配层删掉直接跑业务代码确认报错信息跟最初一样。这个测试的意义在于确认修复是有效的而不是碰巧环境正常了。5. AI辅助开发的避坑经验与操作建议5.1 给AI的提示词应该写什么这次之后我总结了一套给AI的提示词模板核心是在一开始就声明环境约束而不是等代码生成完再自己去补你是本项目的前端工程师。项目目标是发布到微信小游戏运行环境没有浏览器DOM。请遵守以下约束 1. 不要使用 window、document、localStorage、XMLHttpRequest 等浏览器独有对象 2. 平台存储接口统一封装在 src/platform/storage.ts使用 getStorage 获取实例 3. 业务代码禁止直接调用 wx 全局对象通过平台适配层调用 4. 所有类不允许在构造函数中调用可能依赖环境的API统一提供 init() 方法 5. 使用 ES2017 兼容语法禁止使用 ES2020 新增API 6. 单元测试允许mock storage与platform层但业务代码必须通过接口调用。这套提示词的核心价值不是让AI生成代码而是让AI在生成代码时就避开环境差异。它比后期人工修代码节省了至少两倍时间。5.2 对AI生成代码的信任边界我的经验是AI生成的代码你可以信任它的业务逻辑但不要信任它的环境假设。AI的代码生成模型是在海量通用代码上训练的它见过的代码大多数跑在浏览器或Node环境里这导致它在面对“微信小游戏”这种受限环境时往往会惯性使用它在训练语料里最常见的API组合——浏览器API。这个问题的信号很隐蔽单元测试全绿。因为AI自己写的测试会顺着代码逻辑构造匹配的mock形成“自圆其说”的闭环。信任边界应该划在这里逻辑可以信环境假设不能信。5.3 调试工具与签名工具推荐调试微信小游戏环境时推荐三个工具组合使用比单纯看控制台高效得多微信开发者工具的“真机调试”模式可以在真机上远程调试并查看console信息。Cocos Creator自带的模拟器用于快速验证生命周期与组件绑定。代码层面的运行时断言工具在适配层里加一段环境探测日志启动时打印当前检测到的环境信息和关键API是否可用// 调试辅助运行时环境自检 export function runtimeSelfCheck(): void { const env detectRuntime(); console.log([Runtime], env); console.log([Runtime] storage:, typeof getStorage().getItem function); console.log([Runtime] platform:, getPlatformInfo()); }5.4 一些零碎的踩坑细节这次排查过程中有几个零碎但很重要的细节单独列出来微信小游戏与浏览器环境对ArrayBuffer和Uint8Array的处理在某些API上有差异AI生成二进制处理相关的代码时要特别注意极容易出现测试环境正常但真机数据错乱的情况。Cocos构建小游戏时默认会做代码混淆和压缩有些AI生成的代码使用了动态字符串拼接的模块引用这会在构建模式下直接崩掉。遇到这类情况代码里要避免用变量拼接import路径。不要把调试信息留在生产代码里。微信小游戏有包体体积限制多余的调试代码会占用宝贵空间。我在发布前会用构建脚本自动剔除所有console.log调用和调试开关。6. 复盘后我个人最深的三个体会第一测试全绿真的只是一个起点不是终点的信号。它只证明你在那个特定的mock环境里做对了跟线上跑不跑得通没有必然关系。以后不管是谁给我看测试全绿我都要追问一句全绿是在什么环境下全绿第二AI辅助开发的工作流更适合把“环境适配层”提前写死让AI在整个开发过程中都依赖这个层而不是等集成时再补。如果我在让AI写代码之前就把适配层写好后面至少能省掉一半的报错排查时间。这个经验我现在用在了所有项目上不管是小游戏还是纯前端。第三跨环境项目最怕的就是“假设验证”。AI假设环境存在window、假设测试环境等于真实环境、假设所有API都是全的我也跟着假设了。现在我做技术方案时会把环境差异直接画在纸上每个模块标清楚它跑在什么环境、依赖什么API、由谁提供。这些东西在项目早期花十分钟梳理一遍到集成阶段能帮你避免一整个通宵。《清单之外》的这次翻车总结起来就是一句话测试环境不是生产环境AI不懂环境你也不该假装它懂。把环境差异显式化就是AI辅助开发落地的最重要一课。