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