1. Blender 插件調(diào)試為什么總在 Vscode 里翻車如果你寫過 Blender 插件大概率經(jīng)歷過這個(gè)循環(huán)在 Vscode 里改完.py切回 Blender 點(diǎn)一下運(yùn)行報(bào)錯(cuò)信息一閃而過或者干脆什么都不打印。Blender 自帶的 Text Editor 沒有代碼補(bǔ)全、沒有斷點(diǎn)、沒有變量面板稍微復(fù)雜一點(diǎn)的插件項(xiàng)目根本沒法調(diào)。于是大家都會(huì)去裝jacqueslucke.blender-development這個(gè) Vscode 擴(kuò)展用Blender: Start和Blender: Run Script來跑腳本。但真正上手之后問題一個(gè)接一個(gè)冒出來。最常見的就是ModuleNotFoundError你在 Vscode 里明明pip install過的包到了 Blender 里就找不到。原因很簡單Blender 自帶一套獨(dú)立的 Python 解釋器路徑通常是blender-3.6.18-windows-x64/3.6/python/bin/python.exe它和你系統(tǒng)里的 Conda、Pyenv、系統(tǒng) Python 完全隔離。你在 Vscode 終端里裝的tqdm、requests不會(huì)自動(dòng)出現(xiàn)在 Blender 的 Python 里。第二個(gè)坑是斷點(diǎn)不生效。你在 Vscode 里打了紅點(diǎn)按 F5 啟動(dòng)結(jié)果 Blender 那邊腳本跑完了斷點(diǎn)一次都沒停。這通常是因?yàn)檎{(diào)試器附加的進(jìn)程和實(shí)際執(zhí)行腳本的進(jìn)程不是同一個(gè)或者launch.json里的program指向了錯(cuò)誤的入口文件。第三個(gè)坑是argparse報(bào)unrecognized arguments。Blender 通過 Vscode 擴(kuò)展運(yùn)行腳本時(shí)會(huì)自動(dòng)往命令行塞一堆參數(shù)比如--python c:\Users\xxx\.vscode\extensions\...\launch.py。如果你的腳本頂層寫了parser.parse_args()它就會(huì)因?yàn)檫@些不認(rèn)識(shí)的參數(shù)直接崩掉。這篇內(nèi)容就是圍繞這些真實(shí)場(chǎng)景展開的。我會(huì)給出可復(fù)制的launch.json和settings.json片段演示怎么把調(diào)試請(qǐng)求的 endpoint 和鑒權(quán)改到 TaoToken然后跑通一次完整的斷點(diǎn)調(diào)試流程。適合正在做 Blender 插件開發(fā)、被調(diào)試環(huán)境折磨過的朋友。核心檢索詞就三個(gè)Blender、Vscode、調(diào)試。下面從環(huán)境準(zhǔn)備開始一步步來。2. 前置準(zhǔn)備TaoToken 接入與 Blender 調(diào)試環(huán)境搭建在講配置之前先把兩件事準(zhǔn)備好一是 Blender 側(cè)的 Python 環(huán)境二是 TaoToken 的接入信息。這兩件事沒搞定后面的launch.json配得再漂亮也跑不起來。先說 Blender 的 Python 環(huán)境。假設(shè)你的 Blender 裝在D:\Software\blender-3.6.18-windows-x64那么它的 Python 解釋器路徑就是D:\Software\blender-3.6.18-windows-x64\3.6\python\bin\python.exe你要往這個(gè)解釋器里裝依賴不能直接pip install得用完整路徑調(diào)用D:\Software\blender-3.6.18-windows-x64\3.6\python\bin\python.exe -m ensurepip D:\Software\blender-3.6.18-windows-x64\3.6\python\bin\python.exe -m pip install tqdm requestsensurepip是防止 Blender 自帶的 Python 沒有 pip。裝完之后你可以用下面這條命令驗(yàn)證D:\Software\blender-3.6.18-windows-x64\3.6\python\bin\python.exe -c import tqdm; print(tqdm.__version__)能打印出版本號(hào)說明 Blender 的 Python 環(huán)境已經(jīng)能識(shí)別這個(gè)包了。這一步很關(guān)鍵因?yàn)楹竺嬲{(diào)試時(shí)腳本里from tqdm import tqdm能不能過全看這里。再說 TaoToken 的接入。TaoToken 提供的是兼容 OpenAI 風(fēng)格的 API 接口Base URL 是https://taotoken.net/api你需要在控制臺(tái)生成一個(gè) API Key。這個(gè) Key 后面會(huì)寫進(jìn)調(diào)試配置里用來讓調(diào)試過程中的模型請(qǐng)求走 TaoToken 的通道。具體來說你需要在 Vscode 的調(diào)試配置里設(shè)置環(huán)境變量把OPENAI_BASE_URL指向 TaoToken把OPENAI_API_KEY設(shè)成你生成的 Key。如果你還沒生成 Key可以去控制臺(tái)的 API Keys 頁面創(chuàng)建一個(gè)。地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite生成之后先復(fù)制保存后面配置里要用。另外如果你打算長期做插件開發(fā)、經(jīng)常需要跑 Agent 類的調(diào)試任務(wù)可以了解一下 Coding Plan它更適合高頻調(diào)用場(chǎng)景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite環(huán)境準(zhǔn)備好之后還要確認(rèn) Vscode 里裝了jacqueslucke.blender-development擴(kuò)展。這個(gè)擴(kuò)展是 Blender 官方推薦的 Vscode 調(diào)試工具裝完之后在命令面板里能搜到Blender: Start、Blender: Run Script、Blender: Build and Start這些命令。裝好擴(kuò)展、裝好 Blender Python 依賴、拿到 TaoToken Key三件事齊了就可以進(jìn)配置環(huán)節(jié)。3. 可復(fù)制配置launch.json 與 settings.json 完整片段這一節(jié)是全文的核心直接給可復(fù)制的配置。我會(huì)把launch.json、settings.json以及一個(gè)用于驗(yàn)證的main.py都寫出來你照著改路徑就能用。先看launch.json。這個(gè)文件放在項(xiàng)目根目錄的.vscode文件夾下。它的作用是告訴 Vscode 怎么啟動(dòng) Blender、怎么附加調(diào)試器、怎么把環(huán)境變量傳進(jìn)去。{ version: 0.2.0, configurations: [ { name: Blender: Debug Plugin, type: python, request: launch, program: ${workspaceFolder}/main.py, console: integratedTerminal, justMyCode: false, env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的TaoToken密鑰, BLENDER_USER_SCRIPTS: ${workspaceFolder} }, envFile: ${workspaceFolder}/.env, python: D:\\Software\\blender-3.6.18-windows-x64\\3.6\\python\\bin\\python.exe, args: [], cwd: ${workspaceFolder} }, { name: Blender: Attach, type: python, request: attach, connect: { host: 127.0.0.1, port: 5678 }, justMyCode: false, pathMappings: [ { localRoot: ${workspaceFolder}, remoteRoot: ${workspaceFolder} } ] } ] }這里有幾個(gè)點(diǎn)要解釋。program指向你的入口腳本main.pypython指向 Blender 自帶的解釋器這樣斷點(diǎn)才會(huì)在正確的進(jìn)程里生效。justMyCode設(shè)為false是為了能跟進(jìn) Blender 內(nèi)部的bpy調(diào)用棧排查問題時(shí)很有用。env里把OPENAI_BASE_URL和OPENAI_API_KEY設(shè)好調(diào)試過程中腳本發(fā)起的模型請(qǐng)求就會(huì)走 TaoToken。envFile是可選的如果你不想把 Key 寫在launch.json里可以放到.env文件然后在這里引用。再看settings.json。這個(gè)文件同樣放在.vscode下主要配置 Python 解釋器路徑和 Blender 擴(kuò)展的行為。{ python.defaultInterpreterPath: D:\\Software\\blender-3.6.18-windows-x64\\3.6\\python\\bin\\python.exe, python.analysis.extraPaths: [ ${workspaceFolder}, D:\\Software\\blender-3.6.18-windows-x64\\3.6\\scripts\\modules ], blender.executables: [ { path: D:\\Software\\blender-3.6.18-windows-x64\\blender.exe, name: Blender 3.6.18 } ], blender.addon.reloadOnSave: true, files.associations: { *.py: python } }python.analysis.extraPaths里加了 Blender 的scripts/modules目錄這樣 Vscode 的 Pylance 才能識(shí)別bpy、bpy_extras這些模塊不會(huì)滿屏紅線。blender.addon.reloadOnSave設(shè)為true保存腳本時(shí)擴(kuò)展會(huì)自動(dòng)重載插件省去手動(dòng)重啟的麻煩。最后給一個(gè)用于驗(yàn)證的main.py。這個(gè)腳本故意寫得簡單但包含了幾個(gè)容易踩坑的點(diǎn)不用argparse、用traceback打印完整異常、把模型請(qǐng)求指向 TaoToken。import os import sys import traceback sys.path.append(os.path.dirname(os.path.abspath(__file__))) def main(): print(Start script inside Blender) print(Base URL:, os.environ.get(OPENAI_BASE_URL)) print(Key prefix:, os.environ.get(OPENAI_API_KEY, )[:8]) class Args: json scene_json/6.json output_dir output/6 input_image input_text input_scene scene_json/6.json wall_height 3.2 export_glb False args Args() try: run_pipeline(args) print(Script completed successfully.) except Exception: print(Exception occurred:) traceback.print_exc() def run_pipeline(args): print(Running pipeline with:, args.json) import tqdm for i in tqdm.tqdm(range(3), descprocessing): print(step, i) if __name__ __main__: main()注意這里沒有用if __name__ __main__作為唯一入口而是直接調(diào)用main()。因?yàn)?Blender 通過runpy.run_path()執(zhí)行腳本時(shí)__name__不等于__main__如果你把邏輯全放在if __name__ __main__里面它根本不會(huì)執(zhí)行。這是很多人第一次調(diào)試時(shí)遇到的「腳本跑了但沒輸出」的根因。4. 驗(yàn)證請(qǐng)求跑通一次完整斷點(diǎn)調(diào)試配置寫完之后要驗(yàn)證它真的能跑。這一節(jié)我按操作順序走一遍從啟動(dòng) Blender 到斷點(diǎn)命中再到確認(rèn) TaoToken 請(qǐng)求生效。第一步在 Vscode 里打開你的插件項(xiàng)目確認(rèn).vscode/launch.json和.vscode/settings.json都在。然后在main.py的run_pipeline函數(shù)里for i in tqdm.tqdm(...)這一行左側(cè)點(diǎn)一下打一個(gè)紅點(diǎn)斷點(diǎn)。第二步按CtrlShiftP打開命令面板輸入Blender: Start選擇你配置好的 Blender 3.6.18 路徑。這時(shí)候 Blender 會(huì)啟動(dòng)Vscode 底部狀態(tài)欄會(huì)顯示 Blender 已連接。等 Blender 界面完全加載出來再進(jìn)行下一步。第三步回到 Vscode按 F5 或者點(diǎn)擊「運(yùn)行和調(diào)試」面板里的Blender: Debug Plugin。這時(shí)候調(diào)試器會(huì)啟動(dòng)終端里應(yīng)該能看到類似這樣的輸出Start script inside Blender Base URL: https://taotoken.net/api Key prefix: sk-xxxxx Running pipeline with: scene_json/6.json如果斷點(diǎn)配置正確執(zhí)行到for i in tqdm.tqdm(...)那一行時(shí)Vscode 會(huì)停下來左側(cè)變量面板能看到args對(duì)象、i的值。你可以按 F10 單步跳過按 F11 單步進(jìn)入觀察tqdm的迭代過程。這就是斷點(diǎn)生效的標(biāo)志。第四步驗(yàn)證 TaoToken 請(qǐng)求。在run_pipeline里加一段調(diào)用模型接口的代碼比如用requests發(fā)一個(gè) chat completions 請(qǐng)求import requests import json def call_model(prompt): base_url os.environ.get(OPENAI_BASE_URL) api_key os.environ.get(OPENAI_API_KEY) url f{base_url}/v1/chat/completions headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { model: gpt-4o-mini, messages: [{role: user, content: prompt}] } resp requests.post(url, headersheaders, datajson.dumps(payload), timeout30) print(status:, resp.status_code) print(body:, resp.text[:200]) return resp.json()在斷點(diǎn)停下之后在調(diào)試控制臺(tái)里手動(dòng)調(diào)用call_model(hello)觀察返回。如果status是 200body里有正常的choices字段說明請(qǐng)求已經(jīng)通過 TaoToken 走通了。如果返回 401說明 Key 沒配對(duì)如果返回連接錯(cuò)誤說明 Base URL 寫錯(cuò)了。這一步能把「配置對(duì)不對(duì)」和「網(wǎng)絡(luò)通不通」兩個(gè)問題分開定位。第五步確認(rèn)調(diào)試器附加模式。如果你不想每次按 F5 重啟可以用Blender: Attach配置。先在 Blender 的 Python 里插入import debugpy; debugpy.listen(5678)然后 Vscode 里選Blender: Attach啟動(dòng)就能附加到已經(jīng)運(yùn)行的 Blender 進(jìn)程上。這種方式適合調(diào)試長時(shí)間運(yùn)行的插件不用反復(fù)重啟 Blender。整個(gè)流程跑下來你應(yīng)該能看到Blender 啟動(dòng)、腳本執(zhí)行、斷點(diǎn)命中、變量可見、TaoToken 請(qǐng)求返回 200。這五件事都成立調(diào)試環(huán)境就算搭好了。5. 常見報(bào)錯(cuò)排查401、ModuleNotFoundError 與斷點(diǎn)失效配置跑通之前大概率會(huì)撞上幾個(gè)典型報(bào)錯(cuò)。這一節(jié)我把最常見的幾個(gè)列出來對(duì)照著排查。第一個(gè)是ModuleNotFoundError: No module named tqdm。這個(gè)報(bào)錯(cuò)說明 Blender 自帶的 Python 里沒裝這個(gè)包。解決辦法就是用 Blender 的 Python 完整路徑去裝D:\Software\blender-3.6.18-windows-x64\3.6\python\bin\python.exe -m pip install tqdm裝完之后在 Vscode 的調(diào)試控制臺(tái)里執(zhí)行import sys; print(sys.executable)確認(rèn)輸出的是 Blender 的 Python 路徑而不是系統(tǒng) Python。如果輸出的是系統(tǒng) Python說明launch.json里的python字段沒生效檢查路徑有沒有寫錯(cuò)。第二個(gè)是ModuleNotFoundError: No module named membank也就是你自己的包找不到。這是因?yàn)?Blender 執(zhí)行腳本時(shí)工作目錄和sys.path跟你預(yù)期的不一樣。解決辦法是在腳本頂部手動(dòng)把項(xiàng)目根目錄加進(jìn)去import sys import os sys.path.append(os.path.dirname(os.path.abspath(__file__)))注意__file__在 Blender 的runpy環(huán)境下可能不是你想象的值更穩(wěn)妥的寫法是寫死項(xiàng)目根目錄或者用環(huán)境變量傳進(jìn)去。第三個(gè)是 401 錯(cuò)誤。如果你在調(diào)試控制臺(tái)里看到status: 401說明 TaoToken 的 Key 沒配對(duì)。檢查三件事launch.json里的OPENAI_API_KEY是不是完整的 Key、有沒有多余空格、.env文件里的值有沒有被覆蓋。可以在腳本里打印 Key 的前 8 位確認(rèn)print(Key prefix:, os.environ.get(OPENAI_API_KEY, )[:8])如果打印出來是空的說明環(huán)境變量根本沒傳進(jìn)去檢查launch.json的env字段拼寫。第四個(gè)是local proxy failed或者連接超時(shí)。這類報(bào)錯(cuò)通常是 Base URL 寫錯(cuò)了。TaoToken 的 API 地址是https://taotoken.net/api注意結(jié)尾沒有斜杠拼接路徑時(shí)是{base_url}/v1/chat/completions。如果你寫成https://taotoken.net/api/拼出來就會(huì)多一個(gè)斜杠某些 HTTP 客戶端會(huì)報(bào)錯(cuò)。第五個(gè)是斷點(diǎn)不生效。表現(xiàn)是腳本跑完了斷點(diǎn)一次沒停。排查順序先確認(rèn)launch.json里justMyCode是false再確認(rèn)program指向的入口文件和你實(shí)際執(zhí)行的是同一個(gè)最后確認(rèn) Vscode 的 Python 擴(kuò)展版本和 Blender 擴(kuò)展版本兼容。如果還是不行改用Blender: Attach模式手動(dòng)debugpy.listen再附加通常能繞過這個(gè)問題。第六個(gè)是argparse報(bào)unrecognized arguments。這個(gè)前面提過根因是 Blender 往命令行塞了額外參數(shù)。解決辦法就是別用argparse改用一個(gè)簡單的Args類手動(dòng)構(gòu)造參數(shù)class Args: json scene_json/6.json output_dir output/6 wall_height 3.2 export_glb False args Args()這樣不管 Blender 傳什么參數(shù)進(jìn)來你的腳本都不受影響。第七個(gè)是reading choices相關(guān)的解析錯(cuò)誤。如果你在腳本里手動(dòng)解析模型返回的 JSON遇到choices字段讀不到先打印完整的resp.text看看返回結(jié)構(gòu)。有時(shí)候是模型名寫錯(cuò)了有時(shí)候是請(qǐng)求體格式不對(duì)。TaoToken 兼容 OpenAI 格式model字段填gpt-4o-mini這類標(biāo)準(zhǔn)名稱即可。排查的時(shí)候有個(gè)通用技巧在except里用traceback.print_exc()而不是只print(e)。前者會(huì)打印完整的調(diào)用棧和出錯(cuò)行號(hào)后者只給一行信息定位問題效率差很多。6. 把調(diào)試鏈路固定下來TaoToken 接入與后續(xù)擴(kuò)展配置跑通一次之后建議把整套東西固定成項(xiàng)目模板下次開新插件直接復(fù)制。具體做法是在項(xiàng)目根目錄建一個(gè).vscode文件夾把launch.json、settings.json、.env三個(gè)文件放進(jìn)去.env里只寫 Keylaunch.json里用envFile引用。這樣 Key 不會(huì)進(jìn)版本控制團(tuán)隊(duì)協(xié)作時(shí)各自填自己的。TaoToken 的接入點(diǎn)主要有三個(gè)模型對(duì)話用于快速驗(yàn)證接口通不通API Keys 用于生成和管理密鑰接入文檔用于查具體的請(qǐng)求格式和參數(shù)。調(diào)試過程中如果遇到鑒權(quán)或路徑問題優(yōu)先查文檔。https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你用的是 Claude Code 做插件開發(fā)TaoToken 也支持 Anthropic 風(fēng)格的接入配置方式類似把 Base URL 和 Key 填到對(duì)應(yīng)的環(huán)境變量里就行。長期做 Agent 類調(diào)試的話Coding Plan 的額度更適合高頻場(chǎng)景。最后說一個(gè)實(shí)際經(jīng)驗(yàn)Blender 插件調(diào)試最耗時(shí)間的不是寫代碼而是環(huán)境隔離帶來的各種「找不到模塊」「斷點(diǎn)不生效」。把 Blender 的 Python 路徑、sys.path追加、launch.json的python字段這三件事一次性配對(duì)后面基本就不會(huì)再被這類問題卡住。調(diào)試配置這東西配一次省半年。