1. 为什么你的 VS Code 跑不起来 Python解释器、虚拟环境与调试器三件套刚装好 VS Code 的人十有八九会经历同一个瞬间新建一个hello.py敲下print(hi)按下运行然后——要么弹出一句ModuleNotFoundError要么右下角一直转圈要么干脆提示找不到 Python。这不是你手笨而是 VS Code 本身只是一个编辑器它不自带 Python也不自带运行环境。它需要你明确告诉它三件事用哪个 Python 解释器、在哪个环境里跑、出错了怎么调试。把这三件事讲清楚就是这篇 VS Code 配置 Python 环境全攻略要干的事。它适合刚接触 VS Code 的 Python 开发者尤其是从 IDLE、PyCharm 或者 Jupyter Notebook 转过来的人。你会得到一套可以直接复制的settings.json和launch.json以及每一步的验证动作确保不是“看起来配好了”而是真的能跑通第一个项目。我先把结论摆出来VS Code 的 Python 开发体验90% 取决于解释器选得对不对、虚拟环境建得规不规范、调试配置写得完不完整。插件只是锦上添花。很多人一上来装十几个插件结果解释器还是系统自带的那个老版本pip install装到全局项目之间互相污染最后怪 VS Code 不好用。顺序反了。正确的顺序是先确认本机 Python 本体可用再在项目里创建独立虚拟环境接着让 VS Code 选中这个环境的解释器最后写调试配置并验证。下面按这个顺序走每一步都有可复制的命令和可观察的结果。先做一次基础检查。打开终端Windows 用 PowerShellmacOS/Linux 用默认终端输入python --version如果返回Python 3.11.x之类的版本号说明本体在。如果提示找不到命令Windows 上试py --versionmacOS/Linux 上试python3 --version。这里有个坑Windows 安装 Python 时如果没勾选 “Add Python to PATH”命令行就找不到它。解决办法是重新运行安装包选 Modify把 PATH 选项勾上或者手动把 Python 安装目录和 Scripts 目录加进环境变量。确认本体可用后别急着在 VS Code 里点运行。先在项目文件夹里建虚拟环境。假设你的项目目录是D:\code\demomacOS 是~/code/demo进入该目录后执行python -m venv .venv这行命令会在当前目录生成一个.venv文件夹里面是一份独立的 Python 副本。之后所有依赖都装进这里不会污染系统环境。激活它# Windows PowerShell .venv\Scripts\Activate.ps1 # Windows CMD .venv\Scripts\activate.bat # macOS / Linux source .venv/bin/activate激活成功后命令行提示符前面会出现(.venv)。这时候再执行python --version用的就是虚拟环境里的解释器。如果 PowerShell 报“无法加载文件因为在此系统上禁止运行脚本”以管理员身份打开 PowerShell 执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned输入 Y 确认即可。这是执行策略限制不是环境坏了。到这里本机的 Python 和虚拟环境就绪。接下来才是 VS Code 的舞台。记住一句话VS Code 里所有“找不到模块”“提示不对”“调试进不去”的问题先回头看解释器是不是选成了.venv里那个。下一节讲怎么把 TaoToken 这类模型服务接进来让 VS Code 不只是跑代码还能在写代码时直接调用模型能力。2. 在 VS Code 里接入 TaoTokenAPI Key、Base URL 与模型 ID 三件套VS Code 配置 Python 环境除了本地解释器还有一个越来越常见的需求在编辑器里直接调用大模型做代码补全、解释、生成测试。TaoToken 提供统一的 API 入口兼容 OpenAI 风格的调用方式所以你可以用现成的 Python SDK 或者任意支持自定义 Base URL 的插件接进来。这一节把前置准备讲清楚下一节给可复制的配置。先说清楚 TaoToken 是什么、能做什么。它是一个模型 API 聚合服务你拿到一个 API Key就可以通过统一的 Base URL 调用多种模型不用为每个模型单独申请账号、单独配网络。对 Python 开发者来说最直接的用法有两种一是在自己的脚本里用openai库调用二是通过支持自定义端点的 VS Code 插件比如 Continue、Cline 这类接入在编辑器里直接对话。适合谁如果你正在学 Python想让模型帮你解释报错、补全函数、写单元测试或者你在做 Agent、Coding 相关的项目需要一个稳定的模型调用入口那这套流程就适用。如果你只是想让 VS Code 跑本地 Python 脚本不涉及模型调用那第一节的内容就够了这一节可以跳过。接入需要三样东西我称之为三件套第一API Key。去 TaoToken 的控制台创建地址是https://taotoken.net/console。创建后复制保存它只显示一次。注意不要把它硬编码进提交到 Git 的代码里后面会讲怎么用环境变量管理。第二Base URL。TaoToken 的 API 地址是https://taotoken.net/api。注意这里不带任何查询参数就是干净的 API 根路径。很多 OpenAI 兼容的库要求你填base_url填这个就对了。第三Model ID。也就是你要调用的具体模型名称。这个以控制台或文档里列出的为准不同模型 ID 不一样。填错模型 ID 会直接报模型不存在的错误这是新手最常见的坑之一。把这三件套准备好就可以在 Python 里验证了。先装 SDKpip install openai注意这条命令要在激活了.venv的终端里执行这样依赖才装进项目环境。装完后写一个最小验证脚本test_taotoken.pyimport os from openai import OpenAI client OpenAI( api_keyos.environ.get(TAOTOKEN_API_KEY), base_urlhttps://taotoken.net/api, ) resp client.chat.completions.create( model你的模型ID, messages[{role: user, content: 用一句话解释什么是虚拟环境}], ) print(resp.choices[0].message.content)运行前先设置环境变量。Windows PowerShell$env:TAOTOKEN_API_KEY你的KeymacOS / Linuxexport TAOTOKEN_API_KEY你的Key然后python test_taotoken.py。如果终端打印出一句关于虚拟环境的解释说明三件套全部正确。如果报 401说明 Key 不对或没读到如果报连接错误检查 Base URL 是否写成了带路径的形式如果报模型不存在回去核对 Model ID。这里要提醒一句环境变量只在当前终端会话有效关掉就没了。长期使用建议写进.env文件配合python-dotenv读取并把.env加进.gitignore。这样既方便又不会泄露 Key。下一节进入 VS Code 的配置文件把解释器、格式化和调试一次性配好。3. 可复制配置settings.json、launch.json 与虚拟环境路径怎么写这一节是整篇的核心给你可以直接粘贴的配置片段。VS Code 的 Python 相关配置分两个层级工作区级的.vscode/settings.json管解释器路径、格式化、lint.vscode/launch.json管调试。两个文件都放在项目根目录的.vscode文件夹里。如果文件夹不存在手动建一个。先看settings.json。这个文件控制编辑器行为。下面这份配置针对“项目内使用.venv虚拟环境”的场景路径按你的操作系统调整{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/Scripts/python.exe, python.terminal.activateEnvironment: true, python.analysis.typeCheckingMode: basic, python.analysis.autoImportCompletions: true, editor.formatOnSave: true, python.formatting.provider: none, [python]: { editor.defaultFormatter: ms-python.black-formatter, editor.codeActionsOnSave: { source.organizeImports: explicit } }, files.exclude: { **/__pycache__: true, **/.pytest_cache: true } }逐项说明。python.defaultInterpreterPath指向虚拟环境里的 Python 可执行文件。Windows 是.venv/Scripts/python.exemacOS/Linux 是.venv/bin/python。这个路径写错后面全盘皆输所以务必用文件管理器确认一下文件真实存在。python.terminal.activateEnvironment设为 true意思是每次在 VS Code 里打开终端自动激活虚拟环境省得你手动敲 activate。python.analysis.typeCheckingMode设为 basicPylance 会做基础类型检查既不啰嗦又能抓明显错误。格式化部分我推荐用 Black。先装扩展ms-python.black-formatter再装包pip install black注意python.formatting.provider设为none因为新版 VS Code 已经弃用旧的格式化配置改用扩展方式。editor.formatOnSave设为 true保存即格式化。source.organizeImports设为explicit保存时自动整理 import 顺序。再看launch.json这是调试配置{ version: 0.2.0, configurations: [ { name: Python: 当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, cwd: ${workspaceFolder}, envFile: ${workspaceFolder}/.env, justMyCode: true }, { name: Python: 当前文件不进入第三方库, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, justMyCode: true } ] }关键点type用debugpy这是新版 Python 调试器的类型名老教程里写的python已经过时。program用${file}表示调试当前打开的文件。console用integratedTerminal这样input()之类的交互能正常工作如果选internalConsole输入会卡住。cwd设为工作区根目录保证相对路径导入不出错。envFile指向.env调试时自动加载环境变量这样你的TAOTOKEN_API_KEY就不用每次手动设。如果你用 TaoToken 做模型调用还想在编辑器里直接对话可以装 Continue 这类插件在它的配置里填三件套Base URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填控制台列出的模型名。这样写代码时选中一段就能让模型解释或重构。配置入口在插件自己的设置面板不在settings.json里别找错地方。配置写完保存。VS Code 右下角状态栏会显示当前解释器点一下可以切换。如果显示的是.venv路径说明settings.json生效了。下一节做实际验证跑通第一个项目。4. 逐项验证从 hello.py 到断点调试确认每一步真的生效配置写完不代表能用必须逐项验证。这一节给你一套可执行的检查清单每步都有预期结果。全部通过说明你的 VS Code Python 环境真的跑通了。第一步验证解释器。在项目根目录新建hello.py内容import sys print(Python 路径:, sys.executable) print(版本:, sys.version)按CtrlShiftP打开命令面板输入Python: Select Interpreter选择.venv里的那个。然后打开集成终端Ctrl确认提示符前有(.venv)。运行python hello.py。预期输出里sys.executable应该指向你项目下的.venv而不是系统 Python。如果指向系统路径说明解释器没选对回上一步重选。第二步验证依赖隔离。在激活的终端里执行pip install requests pip listpip list应该只列出少量包包括刚装的requests而不是系统环境里一大堆全局包。这就证明虚拟环境隔离生效了。再写一段代码验证导入import requests resp requests.get(https://taotoken.net/api, timeout5) print(状态码:, resp.status_code)这里只是验证网络库可用状态码是多少不重要能打印出来就说明requests装对了、导入路径正确。第三步验证调试。在hello.py里加一个函数打上断点def add(a, b): result a b return result if __name__ __main__: print(add(1, 2))在result a b这一行左侧点一下出现红点。按 F5选择 “Python: 当前文件”。程序会在断点处停下左侧变量面板能看到a、b的值按 F10 单步执行能看到result变成 3。如果 F5 直接跑完没停检查断点是否打在可执行行上以及launch.json的program是否指向当前文件。第四步验证格式化。故意把代码写乱比如x12没有空格保存。如果配置了 Black它会自动变成x 1 2。如果没变检查black-formatter扩展是否安装并启用以及settings.json里[python]段的defaultFormatter是否指向它。第五步验证模型调用。如果你接了 TaoToken运行第二节的test_taotoken.py确认能拿到模型返回。这一步通过说明你的 VS Code 不仅能跑本地 Python还能在开发过程中调用模型辅助。五步全过你的环境就是真的可用。任何一步失败先别怀疑配置本身按顺序回退检查解释器路径 → 虚拟环境激活 → 依赖安装位置 → 调试器类型。下一节集中处理最常见的报错。5. 常见报错排查ModuleNotFoundError、401 与 local proxy failed 怎么解这一节按真实报错来。你在 VS Code 里配 Python 环境大概率会遇到下面几类错误。我把报错原文、原因和解决动作一一对应照着做就行。第一类ModuleNotFoundError: No module named xxx。这是最高频的。原因几乎只有一个你pip install装到了系统 Python但 VS Code 用的是.venv里的解释器两者不是同一个。验证方法在 VS Code 集成终端里执行which pythonmacOS/Linux或where pythonWindows看输出路径是不是项目下的.venv。如果不是先激活虚拟环境再装包。另一个可能是终端和编辑器用的解释器不一致解决办法是在命令面板执行Python: Select Interpreter重新选一次然后重启终端。第二类401 Unauthorized或Incorrect API key provided。这是调用 TaoToken 时 Key 的问题。检查三点Key 是否复制完整有没有多余空格环境变量名是否和代码里os.environ.get的一致环境变量是否在当前终端会话里设置过。如果你用.env文件确认launch.json里的envFile路径正确且文件里写的是TAOTOKEN_API_KEYxxx这种格式不要加引号。改完重启调试会话环境变量才会重新加载。第三类local proxy failed或连接超时。这类报错通常和本机网络配置有关。先确认 Base URL 写的是https://taotoken.net/api没有多余路径或参数。再检查系统里是否设置了全局代理如果有尝试在终端里临时取消代理环境变量再运行。还有一种情况是公司网络限制换一个网络环境测试。注意这里不涉及任何绕过网络管理的手段只是排查本机配置。第四类Reading choices failed或返回结构解析错误。这通常说明请求发出去了但返回的不是预期的 JSON 结构。原因可能是 Model ID 填错服务端返回了错误信息而不是正常的 choices 数组。解决办法是打印完整响应print(resp)看返回体里有没有error字段。如果有按错误信息调整 Model ID 或参数。另外确认 SDK 版本老版本openai库的调用方式和新版不同建议pip install -U openai升级到最新。第五类调试时提示OAuth或认证相关错误。如果你用的是某些需要登录的插件可能是登录态过期。重新在插件里登录一次即可。如果是 TaoToken 的 API 调用报认证错误回到第二类处理。第六类Pylance 报一堆红色波浪线但代码能跑。这多半是类型检查太严或解释器没选对。先把python.analysis.typeCheckingMode调成basic或off再确认解释器。如果只是第三方库没有类型存根可以在settings.json里加python.analysis.diagnosticSeverityOverrides忽略特定规则但更推荐装对应的types-xxx包。排查的核心思路是先确认解释器再确认依赖装在哪最后确认网络和 Key。这三层里解释器问题占七成。把sys.executable打印出来很多问题一眼就清楚了。6. 把环境固化成习惯依赖清单、任务配置与长期编码工作流环境配好只是开始真正省时间的是把它固化成可重复的流程。这一节讲三个习惯让你的 VS Code Python 项目换台机器也能快速跑起来。第一个习惯用requirements.txt管理依赖。每次装完包执行pip freeze requirements.txt换环境时激活虚拟环境后执行pip install -r requirements.txt这样依赖版本一致不会出现“我这儿能跑你那儿报错”。如果你用 TaoToken 做模型调用把openai也写进清单。注意不要把 Key 写进任何提交到仓库的文件用.env加.gitignore管理。第二个习惯用 VS Code 任务tasks.json把常用命令固化。在.vscode/tasks.json里写{ version: 2.0.0, tasks: [ { label: 运行当前文件, type: shell, command: ${command:python.interpreterPath}, args: [${file}], group: { kind: build, isDefault: true }, presentation: { reveal: always, panel: shared } } ] }之后按CtrlShiftB就能直接运行当前文件不用切终端。这个任务用的是当前选中的解释器路径所以和虚拟环境联动不会跑错 Python。第三个习惯长期做编码或 Agent 项目的话考虑用 Coding Plan 这类方案统一管理模型调用额度。地址是https://taotoken.net/coding-plan。它的好处是你不用每次单独申请和配置直接在一个入口下调用多种模型适合需要频繁切换模型做对比或做多模型 Agent 的场景。如果你只是偶尔调用按量用 API 就够了。再给一个实用技巧VS Code 里按Ctrl鼠标左键点击函数名能直接跳到定义包括第三方库的源码。这个功能配合 Pylance读源码效率很高。另外CtrlShiftP输入Python: Run Python File in Terminal可以快速运行不用记快捷键。最后把.vscode文件夹提交到仓库settings.json和launch.json不含敏感信息这样团队里每个人拉下来就是统一环境。Key 放在各自的.env里互不影响。这套流程跑顺之后你新建一个 Python 项目的时间会从半小时压缩到两分钟。环境配置这件事一次做对长期受益。