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