企业官网建设流程全解析

测试全绿，结果一进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 API，iOS低版本微信的基础库不支持，真机上一跑就挂。测试环境的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 用一张表看问题

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辅助开发落地的最重要一课。