最近在做一款微信小游戏《清单之外》整个开发过程大量借助 AI 编码助手来写逻辑前期进展顺利到一度让我产生“一个人AI就能做完整个项目”的错觉。核心玩法模块、任务流程、数据管理所有我能想到的纯逻辑部分AI 都写得像模像样单元测试更是全线绿灯。可就在我把代码接入 Cocos 引擎准备构建出包做真机预览的时候项目翻车了启动直接白屏控制台报错一堆看不懂的英文。最讽刺的是测试全绿的那一刻我还专门截了图结果进引擎连个初始场景都渲染不出来。这篇复盘就是把“测试全绿”和“进 Cocos 失败”之间的矛盾掰开揉碎讲清楚帮你绕过我在这一周时间里踩过的大坑也聊聊 AI 辅助游戏开发真正安全的使用边界。这个项目适合两类人看一类是想用 AI 做微信小游戏但还没打通整套流程的独立开发者另一类是正在被“单测通过但实际运行失败”折磨的同行。这篇不会只讲鸡汤式的复盘结论会把具体报错、排查顺序、根因定位过程全部摆出来你甚至可以把它当成一份踩坑排查手册来用。1. 《清单之外》的诞生过程AI 确实帮我写了六成代码1.1 玩法定位和模块拆分《清单之外》的灵感来源很朴素把现实里的待办清单做成一个微缩的像素风小游戏玩家需要按顺序完成一系列“任务”但任务之间存在隐藏的因果关联必须找到清单之外的解法才能真正过关。我定义好玩法后先把程序拆成这几个核心模块任务数据模型与管理器增删改查、排序、状态流转关卡配置表与解析器含隐藏触发条件简单的事件驱动系统任务完成、阶段解锁、全局通知存档系统本地持久化核心控制系统游戏流程的总入口这类玩法有个明显特点逻辑层很重渲染层很轻。我当时想如果让 AI 把逻辑层全部写完我自己只负责场景搭建和 UI 绑定开发周期能压缩到三分之一。事实证明前半句是对的——AI 确实写出了全部逻辑层后半句出了大问题因为“逻辑层写得对”和“逻辑层能在引擎里跑得通”并不是一回事。1.2 与 AI 协作的节奏一次给一个小模块我的做法是一次只丢一个模块给 AI不让它尝试“理解整个游戏”。比如先让它实现一个Task类包含基础字段和状态流转方法跑通后再让它实现TaskManager负责增删改查和事件广播然后是关卡配置加载器。整个过程用对话式协作// Task.ts export enum TaskStatus { Locked, Active, Completed, Failed } export class Task { id: string; title: string; status: TaskStatus; hidden: boolean; unlockCondition?: (state: GameState) boolean; constructor(config: any) { this.id config.id; this.title config.title; this.status config.status ?? TaskStatus.Locked; this.hidden config.hidden ?? false; } }AI 写这种语法规整、依赖清晰的模块时表现很好很少出错。每完成一个模块我就用 Vitest 补一组测试验证状态流转是否正确、边界情况是否兜得住。一个周末下来逻辑层的测试报告全绿我甚至额外加了一批“极端情况测试”同一个任务重复完成两次、在未解锁状态强行触发完成、存档数据损坏时重启等全部通过。1.3 “测试全绿”当时的测试结构长什么样这里想还原一下当时的测试结构因为后来复盘时发现这些测试本身就是埋雷的线索。我把所有单元测试都放在纯 Node.js 环境里跑没有任何模拟引擎环境的东西。典型用例大致是这些新建游戏默认生成 10 个任务前 1 个解锁其余锁定完成任务状态改为 Completed触发事件后置任务解锁任务失败倒计时归零且未完成时状态改为 Failed存档读取合法 JSON 能完整恢复损坏 JSON 回退到默认配置这些测试没有任何一行依赖 Cocos 的 API连cc命名空间都没碰过。我当时的判断是“纯逻辑就该和引擎解耦”这个方向本身没错但我严重低估了一件事逻辑和引擎耦合得越晚接入时的爆炸半径就越大。等到我把这段纯逻辑代码整包塞进 Cocos 的脚本目录真正的问题才刚开始显形。2. “测试全绿”和“进 Cocos 失败”为什么不矛盾本质是运行环境的错位2.1 单测跑的是函数引擎跑的是生命周期和渲染管线的总和单元测试里我调用taskManager.toggleComplete(taskId)函数执行完断言状态变了测试就结束了。但在 Cocos 引擎里同样一行代码的生存环境完全不同。引擎不会等你准备好才开始它会按内置的生命周期自动调用组件脚本场景加载时依次执行onLoad、onEnable、start之后每帧执行update节点销毁时执行onDestroy。如果第三方脚本在某个生命周期函数里访问了一个尚未挂载的组件或者触发了一个尚未初始化的模块哪怕这个函数本身的逻辑写得完美无缺游戏照样会挂。我的单测再好也只能说明“函数在其自身依赖齐备时行为正确”它完全不知道“引擎世界里函数的调用时机由谁决定”。打个比方你的菜谱每一步都写得很标准但厨师偏要在锅还没热的时候就倒油下菜菜谱没错锅糊了。我踩的就是这个“锅还没热”的坑——AI 生成了大量逻辑代码但它没有能力感知某段代码会在引擎的哪个时点被触发它写出来的入口函数和 Cocos 组件生命周期的配合完全是脱节的。2.2 AI 学习到的 Cocos 版本和你在用的版本大概率不是同一个这一点当时花了我很长时间才接受。我最初以为“Cocos Creator 就是 Cocos CreatorAPI 应该都差不多”但实际翻文档后发现不同版本的 API 差异相当大。我项目使用的引擎版自身在某些方法名和属性访问方式和旧版差异明显而 AI 编码助手在生成代码时很自然地套用了训练数据里常见的旧版写法比如使用旧版属性检查器装饰器、旧版资源加载方式等编译时直接报错或者运行时静默失败。我在排查中把 AI 生成的代码和官方文档逐条比对发现至少三个小类问题问题类型AI 的写法当前引擎的真实要求资源加载直接用cc.loader.loadRes需通过resources.load并携带类型和回调签名节点查找依赖字符串路径this.node.getChildByName(xx)子节点没在预期层级时返回 null无任何警告生命周期管理在onLoad中大量初始化第三方模块引擎要求onLoad保持轻量模块依赖需在顶部导入或等start阶段再装配单测环境里这些 API 根本不会被执行自然测不出问题。而 AI 生成的所有代码在“语法层面”完全合法Node.js 里的测试照样运行通过因为测试代码压根没跑到这些引擎相关分支。2.3 微信小游戏是“被裁剪过的浏览器”不是完整的浏览器环境还有一个容易被 AI 忽略的点微信小游戏的运行环境并非完整浏览器。它没有window对象里一部分 API没有完整document部分浏览器存储 API 不可用网络请求也要走平台自己的封装。AI 在生成“存档模块”时很自然地用了localStorage处理持久化这在桌面浏览器环境可以工作构建成微信小游戏后直接抛异常。我的单测跑在 Node 环境localStorage根本不存在但测试时我做了 shim 模拟所以又顺利通过了。这类问题最阴的地方在于开发时你不会觉得不对劲因为模拟环境帮你兜底了等进了微信开发者工具或真机预览真正的平台限制才会生效。如果你把“能过测试”当作“能跑”那你的坑已经注定要踩。3. 从“进 Cocos 白屏”到定位根因完整排查链路复盘3.1 第一次报错看起来很吓人但它是个假线索构建和预览成功后打开微信开发者工具页面直接白屏。控制台抛了一大段错误第一行是某个插件内部的is not a function后面跟着十几行栈信息指向完全陌生的第三方小工具模块。我当时以为是某个 npm 包不兼容微信小游戏环境差点走上一条“全量替换依赖”的错误路线。现在回头看这个报错很可能是主代码先崩了之后引发的连锁输出真正的第一位错误也许被大量后续错误刷掉了。排查经验第一条先别急着分析大段报错把报错滚动到最顶部看第一次抛出的错误是什么往往那才是根因。第一个错误可能本身也不准但比后续刷屏的错误靠谱得多。我后来把报错定位到这一条Uncaught TypeError: Cannot read properties of null (reading getComponent)这个错误指向TaskItemController.ts中的某一个this.getComponent(...)调用显然是某个节点没有挂载对应组件。到这一步我还没有把根因和 AI 代码关联起来只当作自己的场景拼装遗漏。3.2 删代码二分定位五分钟后确定了爆炸范围面对这种“启动即崩、错误位置不明确”的情况最快的方案不是逐行读代码而是把一切能关的脚本先关掉再逐步放开。我在场景里把所有脚本组件先全部禁用只保留一个空场景脚本确认白屏问题消失后再每次启用一半脚本观察是否复现。两轮操作后定位到问题出在不依赖 UI 的“存档模块”上——它不仅在TaskManager初始化时被调用还在TaskManager自身“状态加载”流程中被间接引用导致初始化顺序完全错乱。这种二分法听起来朴素但在 AI 生成的代码里特别管用因为你不知道 AI 在模块之间偷偷塞了什么隐藏耦合。删掉一半代码往往能让你迅速确认“是这批代码的问题”而不是靠肉眼在大片代码里硬找。它可以帮你把问题范围缩小到极小之后再去逐行检查可有针对性得多。3.3 拿官方文档逐条核对 AI 生成的 API 调用定位到存档模块后我开始逐个函数核对它使用的引擎 API 和平台 API。对照表让我很快发现AI 在“存档模块”里调用的一个归档 API 在当前引擎版本已经废弃改用异步回调形式的新接口。更关键的是AI 还会在onLoad阶段同步读取归档数据而引擎的实际载入流程要求归档读取必须放在异步回调里处理否则拿到的就是一个空数据。当时我有一段代码类似这样// AI 生成伪代码 this.storage.load(); // 同步加载归档 this.taskManager.init(this.storage.data); // 拿数据初始化任务而当前引擎的实际模式要求storage.load()需要异步回调或带 Promise直接同步执行时数据字段还是默认值。单测里我 mock 了一整套同步数据所以测得很顺但到了引擎中这种时机错位直接导致任务列表没有初始化完成后续 UI 绑定拿到的就是一个空数组场景渲染自然黑屏。核对 AI 生成的代码不能只看“功能对不对”必须看“调用时机对不对、API 版本对不对、平台兼容对不对”三维对齐。3.4 关键转折一条日志暴露了整个链路的问题本质在修完归档读取时机后项目已经能启动到 UI 界面了但任务列表仍然显示为空。此时我加了一行日志打印“存档加载前后各模块的状态和时间戳”才发现整个启动链路的数据流是断的UI 组件的onLoad执行于数据初始化之前界面绑定的 List 在数据到达时已经完成渲染后续数据变更事件没有触发列表刷新。这句日志解决了我长达两天的困惑。单纯看代码AI 写的模块之间逻辑关系是完整的任务事件明明触发了为什么 UI 不刷新原来不是“任务没被创建”而是“UI 感知不到任务创建”。如果我只盯着函数逻辑追可能追到明天也定位不到问题。排查时必须把关注点从“某段代码是否执行”切换到“数据是否按依赖顺序流经了所有需要它的地方”。4. 卡住项目一周的三个具体根因每一条都值得写进避坑清单4.1 生命周期函数的时序错位AI 没有“引擎上下文”的概念第一个根因就是onLoad和start的执行时机。AI 生成的代码把所有初始化都堆在onLoad还按“模块内顺序”假设了外部组件的装配已完成这完全不成立。在 Cocos 中节点树中不同组件的onLoad执行顺序是有规范可循的但通常不保证跨节点的调用先后。如果你的启动逻辑需要其他模块就绪最稳妥的做法是延迟到start或首次update或者显式做依赖注入。修复方案是我在GameBootstrap里增加一个start()方法把任务模块初始化全部挪进去并在 UI 组件里监听“数据就绪”事件再执行渲染。这样修改后任务列表终于能在启动画面结束后正常展示。这里我自己替代 AI 做了一次完整的“生命周期编排”因为 AI 写代码时从头到尾没有一张“节点树展开后谁先谁后”的心智图它天然只能写好模块内部模块间的时序协调必须靠人。4.2 平台 API 兼容性localStorage不是想用就能用第二个根因是存档模块直接使用了localStorage。在常规浏览器开发中localStorage就是一个同步可用的键值存储而微信小游戏环境不提供该接口需要通过平台存储接口封装。我最终写了一个适配层实现与localStorage相同的外部接口签名内部判断运行环境再决定使用哪条存储之路。这样既保留了 AI 写的上层存取逻辑它只依赖我定义的接口不直接依赖具体实现又让代码能安全地跑在微信小游戏环境里。这个问题的教训是AI 编码助手特别擅长生成“用一个常见接口一统天下”的写法但在跨端场景下“常见接口”往往不是“平台支持的接口”。项目只要涉及微信小游戏、字节小游戏等目标就必须在架构层提前定义环境适配接口而不是把平台 API 直接写进业务代码。4.3 构建产物的缓存机制白屏未必是代码本身的错第三个根因更隐蔽我差点怀疑是自己方向错了。在修完代码后重新构建微信开发者工具里仍旧显示旧逻辑的运行结果个别模块的表现和代码完全对不上。排除了人眼疲劳的可能后我意识到是开发者工具的缓存没有清理干净旧代码产物被加载了。对微信小游戏来说构建后的产物带版本号开发者工具默认在某些条件下不主动拉取最新版本必须手动清理缓存或重新编译。我后来在本地构建流程里加入一个明确的步骤每次修改完脚本后先在开发者工具点“清缓存再编译”而不是直接刷新。这看起来和 Cocos 无关但只要你这套流程里嵌着第三方工具缓存问题就一定会以某种形式出现。排查过程中如果代码明明改到“应该没问题”但屏幕表现依旧先怀疑缓存再去怀疑自己的修改。5. 踩坑之后我给 AI 辅助游戏开发重新定了四条军规5.1 让 AI 只写“领域逻辑”永远替它守好引擎边界第一轮合作中我给 AI 的任务描述大多是一句话“写一个任务管理器支持增删改查和状态流转”。现在我会把这句描述改成更保守的版本“请输入一个纯 TypeScript 模块不要引用任何引擎 API数据被创建后通过回调或事件对外通知不负责 UI 渲染”。把“引擎边界的控制权”完全收在自己手里AI 生成的东西必须是一套能在无引擎环境下独立测试的领域逻辑哪怕因此要多做一层适配器转换也值得。5.2 测试策略升级把“纯逻辑测试”和“集成冒烟测试”分开看现在我的测试分两层。第一层是纯逻辑单测继续让 AI 参与验证任务状态流转、关卡条件、存档合并等第二层是“引擎内冒烟测试”只覆盖启动链路最关键的三件事场景能加载、启动流程能初始化、首屏 UI 能完成渲染。冒烟测试不完全靠自动化更多时候用微信开发者工具的预览模式肉眼确认一条核心路径。两层测试都过了我才会继续往上加功能。纯逻辑测试解决的是“这个函数想问题时对不对”集成冒烟测试解决的是“整个游戏醒过来后有没有一口气吊住”。如果你只能做一种宁可偏向第二种因为游戏行业里“函数全对但游戏崩了”的场景占比实在太高。5.3 人工审查聚焦三个差异点生命周期、平台兼容、缓存版本AI 生成的代码不可能靠一次测试全部兜住人工审查不能完全扔掉。我现在每次让 AI 写完一批代码后重点看这三个地方生命周期哪些逻辑在onLoad执行它依赖的其他模块是否已经就绪平台兼容是否用了浏览器专属 API存不存在“这里的接口在目标平台不可用”依赖关系模块间的初始化顺序是否有隐式假设有没有办法让它显式化这三个点全部满足后再交给测试阶段。人工审查的重点不在“逐行读逻辑”那既枯燥又效率低而在于“挑 AI 天然不敏感的风险点”。5.4 把报错原文完整喂回给 AI但只能当线索不能当真排查期间我发现把报错信息直接粘给 AI 后它能很快给出方向性建议比如“可能是缓存问题”或者“检查生命周期调用顺序”。这种反馈对排查有一定帮助但它永远只代表“它从这些文本里关联到的历史案例”不保证和你的版本、你的架构完全一致。我会把报错的定位当作近似解自己再进代码里核对一遍从不盲改。AI 在开发闭环里的定位更像“一个响应速度极快的结对同事”而不是“替你兜底的验收官”。这次项目最大的收获不是“AI 帮我写了多少代码”而是让我彻底认清了 AI 辅助开发的边界它在语法和局部逻辑层面极其可靠但在全局时序、平台差异、运行环境假设层面一无所知。测试全绿从来都不代表游戏能跑真正能兜底的只有一套符合引擎规律的人工审查机制和集成验证流程。想用 AI 做游戏没问题只要你把“AI 擅长写代码”和“AI 不擅长理解运行时环境”这两句话同时记住就能少走我这条弯路。