【blender】使用Vscode进行blender调试：把调试配置改到 TaoToken 的完整实践

1. Blender 插件调试为什么总在 Vscode 里翻车如果你写过 Blender 插件大概率经历过这个循环在 Vscode 里改完.py切回 Blender 点一下运行报错信息一闪而过或者干脆什么都不打印。Blender 自带的 Text Editor 没有代码补全、没有断点、没有变量面板稍微复杂一点的插件项目根本没法调。于是大家都会去装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它和你系统里的 Conda、Pyenv、系统 Python 完全隔离。你在 Vscode 终端里装的tqdm、requests不会自动出现在 Blender 的 Python 里。第二个坑是断点不生效。你在 Vscode 里打了红点按 F5 启动结果 Blender 那边脚本跑完了断点一次都没停。这通常是因为调试器附加的进程和实际执行脚本的进程不是同一个或者launch.json里的program指向了错误的入口文件。第三个坑是argparse报unrecognized arguments。Blender 通过 Vscode 扩展运行脚本时会自动往命令行塞一堆参数比如--python c:\Users\xxx\.vscode\extensions\...\launch.py。如果你的脚本顶层写了parser.parse_args()它就会因为这些不认识的参数直接崩掉。这篇内容就是围绕这些真实场景展开的。我会给出可复制的launch.json和settings.json片段演示怎么把调试请求的 endpoint 和鉴权改到 TaoToken然后跑通一次完整的断点调试流程。适合正在做 Blender 插件开发、被调试环境折磨过的朋友。核心检索词就三个Blender、Vscode、调试。下面从环境准备开始一步步来。2. 前置准备TaoToken 接入与 Blender 调试环境搭建在讲配置之前先把两件事准备好一是 Blender 侧的 Python 环境二是 TaoToken 的接入信息。这两件事没搞定后面的launch.json配得再漂亮也跑不起来。先说 Blender 的 Python 环境。假设你的 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得用完整路径调用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 环境已经能识别这个包了。这一步很关键因为后面调试时脚本里from tqdm import tqdm能不能过全看这里。再说 TaoToken 的接入。TaoToken 提供的是兼容 OpenAI 风格的 API 接口Base URL 是https://taotoken.net/api你需要在控制台生成一个 API Key。这个 Key 后面会写进调试配置里用来让调试过程中的模型请求走 TaoToken 的通道。具体来说你需要在 Vscode 的调试配置里设置环境变量把OPENAI_BASE_URL指向 TaoToken把OPENAI_API_KEY设成你生成的 Key。如果你还没生成 Key可以去控制台的 API Keys 页面创建一个。地址是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite生成之后先复制保存后面配置里要用。另外如果你打算长期做插件开发、经常需要跑 Agent 类的调试任务可以了解一下 Coding Plan它更适合高频调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite环境准备好之后还要确认 Vscode 里装了jacqueslucke.blender-development扩展。这个扩展是 Blender 官方推荐的 Vscode 调试工具装完之后在命令面板里能搜到Blender: Start、Blender: Run Script、Blender: Build and Start这些命令。装好扩展、装好 Blender Python 依赖、拿到 TaoToken Key三件事齐了就可以进配置环节。3. 可复制配置launch.json 与 settings.json 完整片段这一节是全文的核心直接给可复制的配置。我会把launch.json、settings.json以及一个用于验证的main.py都写出来你照着改路径就能用。先看launch.json。这个文件放在项目根目录的.vscode文件夹下。它的作用是告诉 Vscode 怎么启动 Blender、怎么附加调试器、怎么把环境变量传进去。{ 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 自带的解释器这样断点才会在正确的进程里生效。justMyCode设为false是为了能跟进 Blender 内部的bpy调用栈排查问题时很有用。env里把OPENAI_BASE_URL和OPENAI_API_KEY设好调试过程中脚本发起的模型请求就会走 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设为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__作为唯一入口而是直接调用main()。因为 Blender 通过runpy.run_path()执行脚本时__name__不等于__main__如果你把逻辑全放在if __name__ __main__里面它根本不会执行。这是很多人第一次调试时遇到的「脚本跑了但没输出」的根因。4. 验证请求跑通一次完整断点调试配置写完之后要验证它真的能跑。这一节我按操作顺序走一遍从启动 Blender 到断点命中再到确认 TaoToken 请求生效。第一步在 Vscode 里打开你的插件项目确认.vscode/launch.json和.vscode/settings.json都在。然后在main.py的run_pipeline函数里for i in tqdm.tqdm(...)这一行左侧点一下打一个红点断点。第二步按CtrlShiftP打开命令面板输入Blender: Start选择你配置好的 Blender 3.6.18 路径。这时候 Blender 会启动Vscode 底部状态栏会显示 Blender 已连接。等 Blender 界面完全加载出来再进行下一步。第三步回到 Vscode按 F5 或者点击「运行和调试」面板里的Blender: Debug Plugin。这时候调试器会启动终端里应该能看到类似这样的输出Start script inside Blender Base URL: https://taotoken.net/api Key prefix: sk-xxxxx Running pipeline with: scene_json/6.json如果断点配置正确执行到for i in tqdm.tqdm(...)那一行时Vscode 会停下来左侧变量面板能看到args对象、i的值。你可以按 F10 单步跳过按 F11 单步进入观察tqdm的迭代过程。这就是断点生效的标志。第四步验证 TaoToken 请求。在run_pipeline里加一段调用模型接口的代码比如用requests发一个 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()在断点停下之后在调试控制台里手动调用call_model(hello)观察返回。如果status是 200body里有正常的choices字段说明请求已经通过 TaoToken 走通了。如果返回 401说明 Key 没配对如果返回连接错误说明 Base URL 写错了。这一步能把「配置对不对」和「网络通不通」两个问题分开定位。第五步确认调试器附加模式。如果你不想每次按 F5 重启可以用Blender: Attach配置。先在 Blender 的 Python 里插入import debugpy; debugpy.listen(5678)然后 Vscode 里选Blender: Attach启动就能附加到已经运行的 Blender 进程上。这种方式适合调试长时间运行的插件不用反复重启 Blender。整个流程跑下来你应该能看到Blender 启动、脚本执行、断点命中、变量可见、TaoToken 请求返回 200。这五件事都成立调试环境就算搭好了。5. 常见报错排查401、ModuleNotFoundError 与断点失效配置跑通之前大概率会撞上几个典型报错。这一节我把最常见的几个列出来对照着排查。第一个是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 的调试控制台里执行import sys; print(sys.executable)确认输出的是 Blender 的 Python 路径而不是系统 Python。如果输出的是系统 Python说明launch.json里的python字段没生效检查路径有没有写错。第二个是ModuleNotFoundError: No module named membank也就是你自己的包找不到。这是因为 Blender 执行脚本时工作目录和sys.path跟你预期的不一样。解决办法是在脚本顶部手动把项目根目录加进去import sys import os sys.path.append(os.path.dirname(os.path.abspath(__file__)))注意__file__在 Blender 的runpy环境下可能不是你想象的值更稳妥的写法是写死项目根目录或者用环境变量传进去。第三个是 401 错误。如果你在调试控制台里看到status: 401说明 TaoToken 的 Key 没配对。检查三件事launch.json里的OPENAI_API_KEY是不是完整的 Key、有没有多余空格、.env文件里的值有没有被覆盖。可以在脚本里打印 Key 的前 8 位确认print(Key prefix:, os.environ.get(OPENAI_API_KEY, )[:8])如果打印出来是空的说明环境变量根本没传进去检查launch.json的env字段拼写。第四个是local proxy failed或者连接超时。这类报错通常是 Base URL 写错了。TaoToken 的 API 地址是https://taotoken.net/api注意结尾没有斜杠拼接路径时是{base_url}/v1/chat/completions。如果你写成https://taotoken.net/api/拼出来就会多一个斜杠某些 HTTP 客户端会报错。第五个是断点不生效。表现是脚本跑完了断点一次没停。排查顺序先确认launch.json里justMyCode是false再确认program指向的入口文件和你实际执行的是同一个最后确认 Vscode 的 Python 扩展版本和 Blender 扩展版本兼容。如果还是不行改用Blender: Attach模式手动debugpy.listen再附加通常能绕过这个问题。第六个是argparse报unrecognized arguments。这个前面提过根因是 Blender 往命令行塞了额外参数。解决办法就是别用argparse改用一个简单的Args类手动构造参数class Args: json scene_json/6.json output_dir output/6 wall_height 3.2 export_glb False args Args()这样不管 Blender 传什么参数进来你的脚本都不受影响。第七个是reading choices相关的解析错误。如果你在脚本里手动解析模型返回的 JSON遇到choices字段读不到先打印完整的resp.text看看返回结构。有时候是模型名写错了有时候是请求体格式不对。TaoToken 兼容 OpenAI 格式model字段填gpt-4o-mini这类标准名称即可。排查的时候有个通用技巧在except里用traceback.print_exc()而不是只print(e)。前者会打印完整的调用栈和出错行号后者只给一行信息定位问题效率差很多。6. 把调试链路固定下来TaoToken 接入与后续扩展配置跑通一次之后建议把整套东西固定成项目模板下次开新插件直接复制。具体做法是在项目根目录建一个.vscode文件夹把launch.json、settings.json、.env三个文件放进去.env里只写 Keylaunch.json里用envFile引用。这样 Key 不会进版本控制团队协作时各自填自己的。TaoToken 的接入点主要有三个模型对话用于快速验证接口通不通API Keys 用于生成和管理密钥接入文档用于查具体的请求格式和参数。调试过程中如果遇到鉴权或路径问题优先查文档。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 做插件开发TaoToken 也支持 Anthropic 风格的接入配置方式类似把 Base URL 和 Key 填到对应的环境变量里就行。长期做 Agent 类调试的话Coding Plan 的额度更适合高频场景。最后说一个实际经验Blender 插件调试最耗时间的不是写代码而是环境隔离带来的各种「找不到模块」「断点不生效」。把 Blender 的 Python 路径、sys.path追加、launch.json的python字段这三件事一次性配对后面基本就不会再被这类问题卡住。调试配置这东西配一次省半年。