1. 為什么 Cocos Creator 的調(diào)試鏈路總在 VS Code 里斷掉Cocos Creator 調(diào)試配置改到 VS Code 這件事本質(zhì)上是在解決一個(gè)鏈路對(duì)齊問(wèn)題編輯器負(fù)責(zé)把 TypeScript 編譯成 JSB 能跑的 JavaScriptVS Code 負(fù)責(zé)通過(guò)調(diào)試協(xié)議連上模擬器或真機(jī)而launch.json就是這兩端之間的“接頭暗號(hào)”。暗號(hào)對(duì)不上斷點(diǎn)就是灰的控制臺(tái)只會(huì)甩給你一句Not a valid project或者干脆靜默不連。我見過(guò)太多人卡在這一步插件裝了Cocos-JSB配置也加了點(diǎn)綠色三角卻彈VS Code 連接不上 JSB。問(wèn)題往往不在代碼而在三個(gè)地方——address寫成了localhost而不是127.0.0.1、VS Code 打開的文件夾不是模擬器資源目錄、以及 sourceMap 路徑?jīng)]對(duì)齊導(dǎo)致斷點(diǎn)落在編譯后的project.dev.js里而不是你的.ts源文件。這篇內(nèi)容面向的是已經(jīng)在用 Cocos Creator 做 H5 或原生小游戲、但被調(diào)試鏈路折磨過(guò)的開發(fā)者。你會(huì)看到一份可以直接復(fù)制的launch.json片段、逐項(xiàng)驗(yàn)證動(dòng)作以及斷點(diǎn)不生效、sourceMap 錯(cuò)位、Not a valid project這幾類高頻報(bào)錯(cuò)的排查路徑。如果你同時(shí)還在用 AI 輔助寫代碼后面我也會(huì)給出把模型調(diào)用接進(jìn)工作流的配置方式讓調(diào)試和生成在同一個(gè)工程里閉環(huán)。先說(shuō)清楚一個(gè)前提Cocos Creator 的調(diào)試分兩條路。一條是網(wǎng)頁(yè)預(yù)覽調(diào)試走 Chrome DevTools 協(xié)議另一條是模擬器/真機(jī)調(diào)試走 JSB 的調(diào)試端口。launch.json里的Cocos-JSB配置只負(fù)責(zé)第二條路網(wǎng)頁(yè)調(diào)試你直接用瀏覽器 F12 就行不需要 VS Code 介入。很多人混淆這兩者導(dǎo)致配置寫對(duì)了卻連錯(cuò)對(duì)象。另一個(gè)前提是版本差異。Cocos Creator 2.x 和 3.x 的模擬器路徑、project.dev.js的生成位置都不一樣。2.x 的模擬器資源在CocosCreator/resources/cocos2d-x/simulator/下3.x 則改成了CocosCreator/resources/resources/3d/engine/bin/之類的結(jié)構(gòu)。你如果照著 2.x 的教程配 3.x路徑必然對(duì)不上Not a valid project就是這么來(lái)的。所以下面的配置我會(huì)標(biāo)注版本你按自己的版本取用。最后說(shuō)清楚調(diào)試的目標(biāo)讓 VS Code 里在你.ts源文件上打的斷點(diǎn)能在模擬器運(yùn)行到那一行時(shí)停下來(lái)并且變量面板能看到當(dāng)前作用域的值。做不到這一點(diǎn)調(diào)試就是假的。下面所有步驟都圍繞這個(gè)目標(biāo)展開。2. TaoToken 在調(diào)試工作流里的位置與前置準(zhǔn)備在講launch.json之前先把這個(gè)環(huán)節(jié)說(shuō)清楚TaoToken 不是調(diào)試器它不參與斷點(diǎn)命中也不接管 JSB 連接。它解決的是另一個(gè)問(wèn)題——當(dāng)你在調(diào)試過(guò)程中需要讓 AI 幫你讀報(bào)錯(cuò)、改配置、生成測(cè)試用例時(shí)模型調(diào)用走哪里。把模型接入配好調(diào)試時(shí)遇到Not a valid project這類報(bào)錯(cuò)你可以直接把日志貼給模型讓它給排查方向而不是去翻幾年前的論壇帖。TaoToken 的接入地址是https://taotoken.net/api兼容 OpenAI 風(fēng)格的接口。你需要在控制臺(tái)創(chuàng)建一個(gè) API Key然后把它填進(jìn)你用的工具里。對(duì)于 VS Code 里的 AI 編碼插件比如 Cline、Continue 這類配置項(xiàng)通常是三項(xiàng)Base URL、API Key、Model ID。這三件套缺一不可只填 Key 不填 Base URL請(qǐng)求會(huì)打到默認(rèn)的 OpenAI 地址上去直接 401。具體操作路徑打開https://taotoken.net/console創(chuàng)建 Key然后在https://taotoken.net/doc查對(duì)應(yīng)工具的接入文檔。如果你用的是 Claude Code 這類命令行工具接入方式又不一樣需要走h(yuǎn)ttps://taotoken.net/claude-code-anthropic這個(gè)入口看說(shuō)明。模型對(duì)話調(diào)試可以在https://taotoken.net/model-chat里先驗(yàn)證 Key 是否可用確認(rèn)能正常返回再往編輯器里配。這里有個(gè)容易踩的坑很多人把 API Key 直接寫進(jìn)launch.json或者提交到 Git 的配置文件里。launch.json是調(diào)試配置不該放密鑰AI 插件的配置應(yīng)該放在獨(dú)立的 settings 文件或環(huán)境變量里。兩者混在一起既污染調(diào)試配置又有泄露風(fēng)險(xiǎn)。正確的做法是調(diào)試歸調(diào)試模型接入歸模型接入各用各的配置文件。前置準(zhǔn)備清單VS Code 裝好 Cocos Creator 官方插件在編輯器里點(diǎn)“安裝 VS Code 插件”會(huì)自動(dòng)裝、Node.js 環(huán)境正常、模擬器能獨(dú)立啟動(dòng)并跑起來(lái)游戲。這三樣沒(méi)就緒后面配launch.json是空中樓閣。特別是模擬器你必須先讓它在沒(méi)有 VS Code 的情況下能跑再去連調(diào)試器否則你分不清是模擬器本身的問(wèn)題還是調(diào)試配置的問(wèn)題。3. 可復(fù)制的 launch.json 與 settings 配置片段這一節(jié)給可直接粘貼的配置。先給launch.json這是調(diào)試鏈路的核心。在 VS Code 里打開你的項(xiàng)目切到“運(yùn)行和調(diào)試”面板點(diǎn)“創(chuàng)建 launch.json 文件”環(huán)境選Cocos-JSB。如果下拉里沒(méi)有Cocos-JSB說(shuō)明插件沒(méi)裝好或者項(xiàng)目里已存在一個(gè)損壞的launch.json——?jiǎng)h掉它重新創(chuàng)建就能看到選項(xiàng)。這是官方文檔沒(méi)寫清楚但實(shí)際高頻發(fā)生的問(wèn)題。生成的launch.json在.vscode/目錄下把configurations數(shù)組替換成下面這份以 Cocos Creator 2.x 模擬器調(diào)試為例{ version: 0.2.0, configurations: [ { name: Cocos-JSB 模擬器調(diào)試, type: cocos-jsb, request: attach, address: 127.0.0.1, port: 5086, sourceMaps: true, cwd: ${workspaceFolder}, outFiles: [ ${workspaceFolder}/**/*.js ] } ] }逐項(xiàng)說(shuō)明。address必須是127.0.0.1不能寫localhost。這是最容易翻車的一項(xiàng)寫localhost時(shí) VS Code 可能解析到 IPv6 的::1而模擬器監(jiān)聽的是 IPv4結(jié)果就是連接超時(shí)控制臺(tái)報(bào)VS Code 連接不上 JSB。port默認(rèn) 5086如果你改過(guò)模擬器調(diào)試端口這里要同步。sourceMaps打開才能讓斷點(diǎn)映射回.ts源文件關(guān)掉的話斷點(diǎn)只能落在編譯產(chǎn)物里。真機(jī)調(diào)試時(shí)把a(bǔ)ddress改成真機(jī)的局域網(wǎng) IP比如192.168.1.100并確保手機(jī)和電腦在同一網(wǎng)段、防火墻放行 5086 端口。真機(jī)調(diào)試的端口有時(shí)不是 5086以模擬器/真機(jī)啟動(dòng)日志里打印的調(diào)試端口為準(zhǔn)。然后是 AI 插件的配置。以 Cline 為例它的配置在 VS Code 的 settings 里對(duì)應(yīng) 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——必須同時(shí)存在。只填 Key 會(huì) 401只填 Base URL 會(huì)提示缺少認(rèn)證。Model ID 要填 TaoToken 支持的模型標(biāo)識(shí)具體可用列表在文檔里查。如果你用的是 Codex 類工具配置寫在auth.json里結(jié)構(gòu)不同但同樣是這三項(xiàng)Claude Code 則走環(huán)境變量或它自己的配置文件。注意launch.json和 AI 配置不要混。有人圖省事把 API Key 塞進(jìn)launch.json的env字段這既不生效也不安全。調(diào)試配置只管調(diào)試模型接入只管模型接入。4. 驗(yàn)證請(qǐng)求與斷點(diǎn)命中的完整動(dòng)作配置寫完不代表能用必須逐項(xiàng)驗(yàn)證。下面這套動(dòng)作按順序做每一步都有明確的成功標(biāo)志。第一步先讓模擬器獨(dú)立跑起來(lái)。在 Cocos Creator 編輯器頂部把預(yù)覽平臺(tái)切到“模擬器調(diào)試”點(diǎn)運(yùn)行預(yù)覽。等模擬器窗口出現(xiàn)、游戲畫面正常渲染。這一步不涉及 VS Code如果模擬器都起不來(lái)先解決模擬器問(wèn)題。第二步找到模擬器的資源路徑。Windows 下在CocosCreator/resources/cocos2d-x/simulator/win32Mac 下在CocosCreator.app/Contents/Resources/cocos2d-x/simulator/mac/Simulator.app/Contents/Resources。這個(gè)路徑下有src/project.dev.js你的所有腳本被合并編譯進(jìn)了這個(gè)文件。第三步關(guān)鍵動(dòng)作VS Code 打開的文件夾必須是上面這個(gè)模擬器資源路徑而不是你的項(xiàng)目工程目錄。這是Not a valid project報(bào)錯(cuò)的根因。很多人打開的是D:\MyProject但調(diào)試器要的是模擬器資源目錄。Mac 上因?yàn)?app是包Finder 里不能直接拖需要先關(guān)掉 VS Code 所有文件夾再把 Finder 里的路徑拖進(jìn) VS Code 窗口。第四步在打開的模擬器資源目錄里找到src/project.dev.js在你關(guān)心的邏輯對(duì)應(yīng)位置打一個(gè)斷點(diǎn)。因?yàn)樵次募缓喜⒘四愕孟人押瘮?shù)名或關(guān)鍵字符串定位。這也是 Cocos 調(diào)試體驗(yàn)差的地方——幾百個(gè)源文件揉成一個(gè)文件斷點(diǎn)定位靠搜。第五步確保模擬器還在運(yùn)行切到 VS Code 調(diào)試面板下拉選Cocos-JSB 模擬器調(diào)試點(diǎn)綠色三角。成功標(biāo)志VS Code 底部狀態(tài)欄變橙調(diào)試控制臺(tái)出現(xiàn)連接成功日志模擬器里游戲運(yùn)行到你斷點(diǎn)那行時(shí)停住VS Code 高亮當(dāng)前行并顯示變量。如果斷點(diǎn)沒(méi)停先看斷點(diǎn)是不是灰的?；业恼f(shuō)明 sourceMap 沒(méi)生效或路徑?jīng)]對(duì)上。檢查sourceMaps是否為true以及outFiles是否覆蓋了project.dev.js所在目錄。如果斷點(diǎn)是紅的但不停多半是模擬器沒(méi)運(yùn)行到那行或者你打開的文件夾不對(duì)導(dǎo)致斷點(diǎn)注冊(cè)到了錯(cuò)誤的文件上。驗(yàn)證 AI 接入是否可用在模型對(duì)話頁(yè)面發(fā)一條測(cè)試消息能正常返回就說(shuō)明 Key 和 Base URL 沒(méi)問(wèn)題。然后在編輯器插件里發(fā)一條“解釋這段報(bào)錯(cuò)”看是否走通。走不通就回查三件套重點(diǎn)看 Base URL 有沒(méi)有漏掉/api后綴。5. 斷點(diǎn)不生效與 Not a valid project 的排查對(duì)照這一節(jié)按真實(shí)報(bào)錯(cuò)來(lái)。你遇到哪條直接對(duì)號(hào)。Not a valid project九成是 VS Code 打開的文件夾不對(duì)。必須打開模擬器資源目錄含src/project.dev.js的那個(gè)不是項(xiàng)目工程目錄。Mac 上如果拖不進(jìn)去先關(guān)閉所有文件夾再拖。還有一種可能是launch.json里的cwd指向了錯(cuò)誤目錄改成${workspaceFolder}并確保 workspace 就是模擬器資源目錄。VS Code 連接不上 JSB先查address是不是127.0.0.1寫localhost會(huì)因 IPv6 解析失敗。再查端口模擬器啟動(dòng)日志里會(huì)打印實(shí)際調(diào)試端口和launch.json里的port對(duì)齊。真機(jī)調(diào)試還要查防火墻和同網(wǎng)段。401 Unauthorized這是 AI 接入的報(bào)錯(cuò)不是調(diào)試的。說(shuō)明 API Key 無(wú)效或沒(méi)帶上。檢查三件套是否齊全Base URL 是否為https://taotoken.net/apiKey 是否復(fù)制完整前后無(wú)空格。如果用的是 Codex 的auth.json檢查字段名是否寫對(duì)。local proxy failed通常是本地網(wǎng)絡(luò)或代理配置問(wèn)題。如果你在編輯器插件里配了自定義 Base URL確認(rèn)地址可達(dá)。這個(gè)報(bào)錯(cuò)和調(diào)試鏈路無(wú)關(guān)別去改launch.json。reading choices或返回結(jié)構(gòu)解析失敗說(shuō)明請(qǐng)求發(fā)出去了但響應(yīng)格式不對(duì)。多半是 Base URL 少了/api或者 Model ID 填了不支持的模型?；啬Ｐ蛯?duì)話頁(yè)面用同樣的 Key 和模型發(fā)一條能通說(shuō)明是插件配置問(wèn)題不能通說(shuō)明是 Key 或模型問(wèn)題。斷點(diǎn)是灰色空心圓sourceMap 沒(méi)生效。確認(rèn)sourceMaps: true確認(rèn)outFiles路徑匹配確認(rèn)你打開的文件夾里有對(duì)應(yīng)的.map文件。Cocos 2.x 的 sourceMap 有時(shí)不隨構(gòu)建生成需要在構(gòu)建選項(xiàng)里打開 source map 輸出。斷點(diǎn)紅色但不停模擬器沒(méi)運(yùn)行到那行或者你斷點(diǎn)打在project.dev.js里但實(shí)際執(zhí)行的是另一份編譯產(chǎn)物。確認(rèn)模擬器加載的就是你打開的這個(gè)資源目錄。還有一種情況是啟動(dòng)時(shí)的斷點(diǎn)無(wú)法命中——這是 Cocos 的已知行為啟動(dòng)階段的代碼在調(diào)試器 attach 之前就執(zhí)行完了。解決辦法是在啟動(dòng)邏輯里加一個(gè)延時(shí)或等待信號(hào)等調(diào)試器連上再執(zhí)行關(guān)鍵代碼。6. 把調(diào)試鏈路和模型調(diào)用固定成日常配置調(diào)試配置這東西配一次能用很久但前提是你把它固定下來(lái)。我的做法是把launch.json提交到項(xiàng)目倉(cāng)庫(kù)的.vscode/目錄團(tuán)隊(duì)里每個(gè)人拉下來(lái)就能用不用各自摸索。但 API Key 絕對(duì)不能進(jìn)倉(cāng)庫(kù)AI 插件的配置走本地 settings 或環(huán)境變量每個(gè)人填自己的。對(duì)于長(zhǎng)期做 Cocos 開發(fā)、經(jīng)常需要 AI 輔助讀報(bào)錯(cuò)和生成代碼的場(chǎng)景可以考慮用 Coding Plan 這類按量或包月的方案把模型調(diào)用成本固定下來(lái)避免調(diào)試高峰期 Key 額度不夠。入口在https://taotoken.net/coding-plan適合每天都要和模型交互的編碼工作流。如果只是偶爾用模型對(duì)話頁(yè)面按次調(diào)用就夠了?；氐秸{(diào)試本身。Cocos Creator 的 JSB 調(diào)試體驗(yàn)確實(shí)不如 Unity源文件合并、啟動(dòng)斷點(diǎn)不命中、路徑要求苛刻這些都是現(xiàn)實(shí)。但把launch.json的address、port、sourceMaps三項(xiàng)配對(duì)把 VS Code 打開的文件夾切到模擬器資源目錄把 AI 接入的三件套配齊日常開發(fā)里九成的調(diào)試需求是能覆蓋的。剩下的啟動(dòng)斷點(diǎn)問(wèn)題用延時(shí)等待繞過(guò)去就行。最后給一個(gè)實(shí)用技巧在project.dev.js里搜你的函數(shù)名時(shí)用 VS Code 的全局搜索而不是文件內(nèi)搜索因?yàn)楹喜⒑蟮奈募艽笪募?nèi)搜索容易卡。搜到之后在函數(shù)入口打條件斷點(diǎn)條件寫cc.game.isRunning之類的運(yùn)行時(shí)判斷能減少無(wú)關(guān)命中。這套組合用順了調(diào)試效率比反復(fù)重啟模擬器高得多。