1. 为什么 Cocos Creator 的调试链路总在 VS Code 里断掉
Cocos Creator 调试配置改到 VS Code 这件事，本质上是在解决一个链路对齐问题：编辑器负责把 TypeScript 编译成 JSB 能跑的 JavaScript，VS 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/win32，Mac 下在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/api，Key 是否复制完整（前后无空格）。如果用的是 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之类的运行时判断，能减少无关命中。这套组合用顺了，调试效率比反复重启模拟器高得多。
