1. 为什么 Cocos Creator 的调试链路总在 VS Code 里断掉Cocos Creator 调试配置改到 VS Code 这件事本质上是在解决一个链路对齐问题编辑器负责把 TypeScript 编译成 JSB 能跑的 JavaScriptVS Code 负责通过调试协议连上模拟器或真机而launch.json就是这两端之间的“接头暗号”。暗号对不上断点就是灰的控制台只会甩给你一句Not a valid project或者干脆静默不连。我见过太多人卡在这一步插件装了Cocos-JSB配置也加了点绿色三角却弹VS Code 连接不上 JSB。问题往往不在代码而在三个地方——address写成了localhost而不是127.0.0.1、VS Code 打开的文件夹不是模拟器资源目录、以及 sourceMap 路径没对齐导致断点落在编译后的project.dev.js里而不是你的.ts源文件。这篇内容面向的是已经在用 Cocos Creator 做 H5 或原生小游戏、但被调试链路折磨过的开发者。你会看到一份可以直接复制的launch.json片段、逐项验证动作以及断点不生效、sourceMap 错位、Not a valid project这几类高频报错的排查路径。如果你同时还在用 AI 辅助写代码后面我也会给出把模型调用接进工作流的配置方式让调试和生成在同一个工程里闭环。先说清楚一个前提Cocos Creator 的调试分两条路。一条是网页预览调试走 Chrome DevTools 协议另一条是模拟器/真机调试走 JSB 的调试端口。launch.json里的Cocos-JSB配置只负责第二条路网页调试你直接用浏览器 F12 就行不需要 VS Code 介入。很多人混淆这两者导致配置写对了却连错对象。另一个前提是版本差异。Cocos Creator 2.x 和 3.x 的模拟器路径、project.dev.js的生成位置都不一样。2.x 的模拟器资源在CocosCreator/resources/cocos2d-x/simulator/下3.x 则改成了CocosCreator/resources/resources/3d/engine/bin/之类的结构。你如果照着 2.x 的教程配 3.x路径必然对不上Not a valid project就是这么来的。所以下面的配置我会标注版本你按自己的版本取用。最后说清楚调试的目标让 VS Code 里在你.ts源文件上打的断点能在模拟器运行到那一行时停下来并且变量面板能看到当前作用域的值。做不到这一点调试就是假的。下面所有步骤都围绕这个目标展开。2. TaoToken 在调试工作流里的位置与前置准备在讲launch.json之前先把这个环节说清楚TaoToken 不是调试器它不参与断点命中也不接管 JSB 连接。它解决的是另一个问题——当你在调试过程中需要让 AI 帮你读报错、改配置、生成测试用例时模型调用走哪里。把模型接入配好调试时遇到Not a valid project这类报错你可以直接把日志贴给模型让它给排查方向而不是去翻几年前的论坛帖。TaoToken 的接入地址是https://taotoken.net/api兼容 OpenAI 风格的接口。你需要在控制台创建一个 API Key然后把它填进你用的工具里。对于 VS Code 里的 AI 编码插件比如 Cline、Continue 这类配置项通常是三项Base URL、API Key、Model ID。这三件套缺一不可只填 Key 不填 Base URL请求会打到默认的 OpenAI 地址上去直接 401。具体操作路径打开https://taotoken.net/console创建 Key然后在https://taotoken.net/doc查对应工具的接入文档。如果你用的是 Claude Code 这类命令行工具接入方式又不一样需要走https://taotoken.net/claude-code-anthropic这个入口看说明。模型对话调试可以在https://taotoken.net/model-chat里先验证 Key 是否可用确认能正常返回再往编辑器里配。这里有个容易踩的坑很多人把 API Key 直接写进launch.json或者提交到 Git 的配置文件里。launch.json是调试配置不该放密钥AI 插件的配置应该放在独立的 settings 文件或环境变量里。两者混在一起既污染调试配置又有泄露风险。正确的做法是调试归调试模型接入归模型接入各用各的配置文件。前置准备清单VS Code 装好 Cocos Creator 官方插件在编辑器里点“安装 VS Code 插件”会自动装、Node.js 环境正常、模拟器能独立启动并跑起来游戏。这三样没就绪后面配launch.json是空中楼阁。特别是模拟器你必须先让它在没有 VS Code 的情况下能跑再去连调试器否则你分不清是模拟器本身的问题还是调试配置的问题。3. 可复制的 launch.json 与 settings 配置片段这一节给可直接粘贴的配置。先给launch.json这是调试链路的核心。在 VS Code 里打开你的项目切到“运行和调试”面板点“创建 launch.json 文件”环境选Cocos-JSB。如果下拉里没有Cocos-JSB说明插件没装好或者项目里已存在一个损坏的launch.json——删掉它重新创建就能看到选项。这是官方文档没写清楚但实际高频发生的问题。生成的launch.json在.vscode/目录下把configurations数组替换成下面这份以 Cocos Creator 2.x 模拟器调试为例{ version: 0.2.0, configurations: [ { name: Cocos-JSB 模拟器调试, type: cocos-jsb, request: attach, address: 127.0.0.1, port: 5086, sourceMaps: true, cwd: ${workspaceFolder}, outFiles: [ ${workspaceFolder}/**/*.js ] } ] }逐项说明。address必须是127.0.0.1不能写localhost。这是最容易翻车的一项写localhost时 VS Code 可能解析到 IPv6 的::1而模拟器监听的是 IPv4结果就是连接超时控制台报VS Code 连接不上 JSB。port默认 5086如果你改过模拟器调试端口这里要同步。sourceMaps打开才能让断点映射回.ts源文件关掉的话断点只能落在编译产物里。真机调试时把address改成真机的局域网 IP比如192.168.1.100并确保手机和电脑在同一网段、防火墙放行 5086 端口。真机调试的端口有时不是 5086以模拟器/真机启动日志里打印的调试端口为准。然后是 AI 插件的配置。以 Cline 为例它的配置在 VS Code 的 settings 里对应 JSON 片段如下{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: 你的_API_KEY, cline.openAiModelId: claude-sonnet-4-20250514 }这三件套——Base URL、Key、Model ID——必须同时存在。只填 Key 会 401只填 Base URL 会提示缺少认证。Model ID 要填 TaoToken 支持的模型标识具体可用列表在文档里查。如果你用的是 Codex 类工具配置写在auth.json里结构不同但同样是这三项Claude Code 则走环境变量或它自己的配置文件。注意launch.json和 AI 配置不要混。有人图省事把 API Key 塞进launch.json的env字段这既不生效也不安全。调试配置只管调试模型接入只管模型接入。4. 验证请求与断点命中的完整动作配置写完不代表能用必须逐项验证。下面这套动作按顺序做每一步都有明确的成功标志。第一步先让模拟器独立跑起来。在 Cocos Creator 编辑器顶部把预览平台切到“模拟器调试”点运行预览。等模拟器窗口出现、游戏画面正常渲染。这一步不涉及 VS Code如果模拟器都起不来先解决模拟器问题。第二步找到模拟器的资源路径。Windows 下在CocosCreator/resources/cocos2d-x/simulator/win32Mac 下在CocosCreator.app/Contents/Resources/cocos2d-x/simulator/mac/Simulator.app/Contents/Resources。这个路径下有src/project.dev.js你的所有脚本被合并编译进了这个文件。第三步关键动作VS Code 打开的文件夹必须是上面这个模拟器资源路径而不是你的项目工程目录。这是Not a valid project报错的根因。很多人打开的是D:\MyProject但调试器要的是模拟器资源目录。Mac 上因为.app是包Finder 里不能直接拖需要先关掉 VS Code 所有文件夹再把 Finder 里的路径拖进 VS Code 窗口。第四步在打开的模拟器资源目录里找到src/project.dev.js在你关心的逻辑对应位置打一个断点。因为源文件被合并了你得先搜函数名或关键字符串定位。这也是 Cocos 调试体验差的地方——几百个源文件揉成一个文件断点定位靠搜。第五步确保模拟器还在运行切到 VS Code 调试面板下拉选Cocos-JSB 模拟器调试点绿色三角。成功标志VS Code 底部状态栏变橙调试控制台出现连接成功日志模拟器里游戏运行到你断点那行时停住VS Code 高亮当前行并显示变量。如果断点没停先看断点是不是灰的。灰的说明 sourceMap 没生效或路径没对上。检查sourceMaps是否为true以及outFiles是否覆盖了project.dev.js所在目录。如果断点是红的但不停多半是模拟器没运行到那行或者你打开的文件夹不对导致断点注册到了错误的文件上。验证 AI 接入是否可用在模型对话页面发一条测试消息能正常返回就说明 Key 和 Base URL 没问题。然后在编辑器插件里发一条“解释这段报错”看是否走通。走不通就回查三件套重点看 Base URL 有没有漏掉/api后缀。5. 断点不生效与 Not a valid project 的排查对照这一节按真实报错来。你遇到哪条直接对号。Not a valid project九成是 VS Code 打开的文件夹不对。必须打开模拟器资源目录含src/project.dev.js的那个不是项目工程目录。Mac 上如果拖不进去先关闭所有文件夹再拖。还有一种可能是launch.json里的cwd指向了错误目录改成${workspaceFolder}并确保 workspace 就是模拟器资源目录。VS Code 连接不上 JSB先查address是不是127.0.0.1写localhost会因 IPv6 解析失败。再查端口模拟器启动日志里会打印实际调试端口和launch.json里的port对齐。真机调试还要查防火墙和同网段。401 Unauthorized这是 AI 接入的报错不是调试的。说明 API Key 无效或没带上。检查三件套是否齐全Base URL 是否为https://taotoken.net/apiKey 是否复制完整前后无空格。如果用的是 Codex 的auth.json检查字段名是否写对。local proxy failed通常是本地网络或代理配置问题。如果你在编辑器插件里配了自定义 Base URL确认地址可达。这个报错和调试链路无关别去改launch.json。reading choices或返回结构解析失败说明请求发出去了但响应格式不对。多半是 Base URL 少了/api或者 Model ID 填了不支持的模型。回模型对话页面用同样的 Key 和模型发一条能通说明是插件配置问题不能通说明是 Key 或模型问题。断点是灰色空心圆sourceMap 没生效。确认sourceMaps: true确认outFiles路径匹配确认你打开的文件夹里有对应的.map文件。Cocos 2.x 的 sourceMap 有时不随构建生成需要在构建选项里打开 source map 输出。断点红色但不停模拟器没运行到那行或者你断点打在project.dev.js里但实际执行的是另一份编译产物。确认模拟器加载的就是你打开的这个资源目录。还有一种情况是启动时的断点无法命中——这是 Cocos 的已知行为启动阶段的代码在调试器 attach 之前就执行完了。解决办法是在启动逻辑里加一个延时或等待信号等调试器连上再执行关键代码。6. 把调试链路和模型调用固定成日常配置调试配置这东西配一次能用很久但前提是你把它固定下来。我的做法是把launch.json提交到项目仓库的.vscode/目录团队里每个人拉下来就能用不用各自摸索。但 API Key 绝对不能进仓库AI 插件的配置走本地 settings 或环境变量每个人填自己的。对于长期做 Cocos 开发、经常需要 AI 辅助读报错和生成代码的场景可以考虑用 Coding Plan 这类按量或包月的方案把模型调用成本固定下来避免调试高峰期 Key 额度不够。入口在https://taotoken.net/coding-plan适合每天都要和模型交互的编码工作流。如果只是偶尔用模型对话页面按次调用就够了。回到调试本身。Cocos Creator 的 JSB 调试体验确实不如 Unity源文件合并、启动断点不命中、路径要求苛刻这些都是现实。但把launch.json的address、port、sourceMaps三项配对把 VS Code 打开的文件夹切到模拟器资源目录把 AI 接入的三件套配齐日常开发里九成的调试需求是能覆盖的。剩下的启动断点问题用延时等待绕过去就行。最后给一个实用技巧在project.dev.js里搜你的函数名时用 VS Code 的全局搜索而不是文件内搜索因为合并后的文件很大文件内搜索容易卡。搜到之后在函数入口打条件断点条件写cc.game.isRunning之类的运行时判断能减少无关命中。这套组合用顺了调试效率比反复重启模拟器高得多。