每个第一次用 VS Code 写 Python 的人都会遭遇这个翻车现场装好了 VS Code、装好了 Python 扩展、终端里pip install requests跑得干干净净代码也能正常运行。但回到编辑器一看——import requests下面拖着一条长长的波浪线悬停显示Import requests could not be resolved Pylance。更气人的是代码能跑按下运行按钮程序正常执行requests 用得好好的。能跑的代码、飘红的编辑器、消失的自动补全——三个现象同时存在互相矛盾。去搜解决方案答案五花八门重装扩展、改 settings.json、装 black、加 extraPaths……偶尔灵验但你不知道为什么。这篇文章把 VS Code 的 Python 支持拆成三层结构讲透每层的职责和常见坑——所有玄学飘红都能归结到同一句话VS Code 的 Python 支持不是一个整体而是解释器选择 语言服务器 终端激活三个独立组件的拼装任何一层没对齐飘红立刻出现。一、先立三层模型不是装个插件就完事VS Code 本体只是一个编辑器不带任何语言能力。装上 Python 扩展后它实际拉起了三个各自独立、互不感知的组件理论上应对齐理论上应对齐实际可能失联实际可能失联层三终端激活(集成终端的 PATH)决定 pip 装到哪/终端 python 是谁与层一可能不一致层二语言服务器 Pylance(负责智能提示)扫描解释器的 site-packages提供补全/飘红/跳转层一解释器选择(右下角状态栏)决定代码由哪个 Python 运行与 Pylance 独立任何一层没对齐 import 飘红 / 装错地方理解这个模型后开头的翻车现场就不再神秘pip install 装在了层三的 Python 里而 Pylance 在层二扫描的是另一个 Python 的 site-packages——代码能跑是因为运行时层一碰巧选对了飘红是因为层二扫描的目标和层三不一致。这和 pip 排错那篇讲的串仓是同一个病根多版本 Python 并存 归属关系不明。pip 那篇解决终端里装对地方这篇解决编辑器里选对解释器。二、第一层Python 扩展与 Pylance——装什么第一步是装扩展但装之前值得知道装的是什么扩展职责是否必装Python (Microsoft)核心支持运行、调试、解释器管理必装Pylance语言服务器补全、类型检查、飘红必装Python 扩展会自动拉取Python Debugger调试器断点、单步执行必装自动拉取Python Environments环境检测与切换自动拉取Jupyter (Microsoft)在 VS Code 里跑 notebook按需Ruff现代 linter/formatter推荐新装见第五节只装第一个Python扩展其余自动就位——这是最简路径。Pylance 值得单独认识一下因为它是飘红的主角。Pylance 是微软用 TypeScript 写的语言服务器负责静态分析代码补全、类型检查、import 解析、跳转定义。它不运行你的代码只读代码——通过扫描所选解释器的 site-packages 目录来知道有哪些包可用。一个新手常见误解是选对解释器 Pylance 自动跟上——不一定。Pylance 的环境扫描有自己的规则Pylance 只会自动扫描三类位置工作区根目录下名为.venv、env、venv等常见名字的目录、系统已安装的 Conda 环境列表、系统 PATH 里的 Python。如果你的虚拟环境藏在非标准路径比如api/.venv/这种嵌套结构或者名字不叫.venvPylance 会扫不到它——即便你手动选对了解释器飘红依旧。这是第一层坑第四节给解药。三、第二层解释器选择——飘红的九成病因现在讲核心如何让 VS Code 用上你想要的那个 Python。基本操作右下角状态栏会显示当前 Python 版本比如3.12.4 64-bit——点击它顶部会弹出所有可选环境列表。选中目标虚拟环境状态栏变成.venv: 3.12.4就切换成功了。CtrlShiftP→Python: Select Interpreter效果相同。选对解释器后还是飘红的三种病因病因一虚拟环境不在 Pylance 扫描范围内第二节讲的。比如项目结构是myproject/ ├── api/ │ ├── .venv/ ← 藏在 api/ 下Pylance 扫不到 │ └── main.py └── web/此时即使手动选中api/.venv/bin/pythonPylance 依然找不到它的 site-packages。药方在项目根目录的.vscode/settings.json里写入{python.defaultInterpreterPath:./api/.venv/bin/python}这条配置会告诉 VS Code“这个工作区的默认解释器是这里顺便把它的 site-packages 纳入 Pylance 分析”。保存后重新选择解释器飘红即消失。病因二settings.json 层级冲突。VS Code 的设置分三级用户级全局默认、工作区级.vscode/settings.json、文件夹级多根工作区时的子目录配置。优先级从高到低文件夹 工作区 用户。常见坑在公司电脑上设过全局的python.defaultInterpreterPath回家打开个人项目——解释器还是指向公司的路径报找不到文件。解药个人项目一律在工作区级.vscode/settings.json里覆盖这份文件可以提交进 Git团队成员共享配置。病因三python.analysis.extraPaths兜底。如果项目有自定义模块目录不在解释器路径里Pylance 依然会飘红。终极武器{python.analysis.extraPaths:[./my_lib,./src]}把自定义模块根目录加进搜索路径。这是最后手段——优先靠解释器选对解决extraPaths 滥用会让分析变慢且掩盖真实问题。四、第三层终端激活——pip 装对地方的最后保障第三层讲的是集成终端的 Python 和右下角解释器是不是同一个。这一层出问题症状是pip 装了但运行时 import 报错和飘红不同——这次是真报错。正常机制VS Code 的 Python 扩展会自动激活虚拟环境打开新终端时自动执行激活脚本让终端的python命令指向右下角选中的解释器。设置里对应一项{python.terminal.activateEnvironment:true}默认开启。终端提示符前出现(.venv)前缀就是激活成功的标志。常见坑与药方坑一运行按钮走了全局 Python。有时点右上角Run Python File按钮实际执行的是全局解释器而不是 venv——脚本运行时报ModuleNotFoundError但终端里手动运行又正常。药方打开设置搜索python.terminal.activateEnvironment确认是 true如果还犯病可能是实验性功能冲突加一条禁用{python.terminal.activateEnvironment:true,python.terminal.activateEnvInCurrentTerminal:true,python.experiments.optOutFrom:[pythonTerminalEnvVarActivation]}坑二多终端切换后环境丢失。开三个终端窗口其中一个激活了 venv另外两个还是全局——在没激活的终端里pip install包装进了全局 Python项目 import 又炸了。药方习惯性先看终端提示符有没有(.venv)前缀再操作不确定时验证# 看当前终端的 python 到底是谁whichpython# 或python-cimport sys; print(sys.executable)和 pip 那篇的诊断三件套一模一样——操作前先确认我在哪个仓库。坑三脚本 shebang 行绕过环境。写了#!/usr/bin/env python3的脚本直接执行时python3解析到系统 Python 而非 venv。药方统一用#!/usr/bin/env python不带 3或者在 VS Code 里始终通过Run Python File按钮执行。五、第四层格式化与 Linting——Ruff 一统天下传统方案要装一堆Black格式化、isortimport 排序、Pylint/Flake8静态检查——四个工具、四份配置、互相打架。2025-2026 年的答案只剩一个Ruff。Ruff 是 Astral做 uv 的那家用 Rust 写的全能选手一个工具替代 Black isort Flake8 Pylint速度快 10-100 倍。在 VS Code 里的接入只需两步第一步扩展市场搜Ruff安装发布者 charliermarsh。第二步.vscode/settings.json写入{[python]:{editor.defaultFormatter:charliermarsh.ruff,editor.formatOnSave:true,editor.codeActionsOnSave:{source.fixAll:explicit,source.organizeImports:explicit}}}保存即格式化、自动修 lint 错误、自动整理 import——三个动作一次完成。为什么值得从传统工具迁移单二进制、单配置文件ruff.toml或pyproject.toml、CI 与本地行为完全一致。传统 Pylint 每个项目配置半天才安静下来Ruff 默认就够克制。六、第五层调试与 Jupyter调试不需要额外配置。Python 扩展默认使用debugpy在代码行号左侧点一下设断点按 F5 启动调试——变量面板、调用栈、单步执行全部就位。vscode 自动生成的launch.json在多数场景够用进阶远程调试、Django/Flask 专用配置按需添加。Jupyter装上Jupyter扩展Microsoft.ipynb文件直接在 VS Code 里跑。这里有个高频坑notebook 的 kernel 选择和右下角解释器是两回事——每个 notebook 右上角有自己的 kernel 选择器。kernel 选错了单元格里pip install装的包和 import 的包不在一个环境报错又完全一样。药方遇到 notebook import 报错先检查 kernel 选择器而不是终端解释器。七、完整配置模板可以直接抄走的.vscode/settings.json覆盖前文所有防御{// ---- 解释器 ----python.defaultInterpreterPath:${workspaceFolder}/.venv/bin/python,// ---- 终端激活 ----python.terminal.activateEnvironment:true,python.terminal.activateEnvInCurrentTerminal:true,python.experiments.optOutFrom:[pythonTerminalEnvVarActivation],// ---- 格式化Ruff----[python]:{editor.defaultFormatter:charliermarsh.ruff,editor.formatOnSave:true,editor.codeActionsOnSave:{source.fixAll:explicit,source.organizeImports:explicit}},// ---- Pylance 微调 ----python.analysis.typeCheckingMode:basic,python.analysis.autoImportCompletions:true// ---- 兜底非标准路径时启用 ----// python.analysis.extraPaths: [./api, ./src]}配合ruff.toml项目根目录target-version py312 line-length 100 [lint] select [E, F, I, W] # 基础 isort这两份文件提交进 Git团队新人 clone 下来即可开干。八、踩坑排查表症状病因层药方import 飘红但代码能跑层二Pylance 没扫到 site-packages右下角换解释器仍飘红查python.defaultInterpreterPath选对了解释器还是飘红层二venv 在非标准路径settings.json 里显式指定解释器路径运行报ModuleNotFoundError终端里正常层三运行按钮走了全局 Python检查activateEnvironment配置终端pip install后 import 还是失败层三终端没激活 venv看终端提示符有无(.venv)which python验证自定义模块 import 飘红层二extraPaths 缺失python.analysis.extraPaths加入模块根目录Jupyter 单元格 import 报错层五kernel 与解释器不一致notebook 右上角换 kernel不是右下角换了电脑后环境全乱层二settings.json 层级冲突工作区级配置覆盖用户级格式化不生效层四默认 formatter 没设[python]段指定editor.defaultFormatterPylance 类型报错太严格层二检查模式过紧typeCheckingMode降到basic或off九、结语回头看VS Code 的 Python 开发所有玄学共享同一个根源三层组件解释器、Pylance、终端各自独立、各有各的我在哪问题而 VS Code 从不主动告诉你哪层失联了。飘红是层二在喊我扫不到包运行报错是层三在喊我这里没有包——同一个症状两种病因排查思路完全不同。一句话金句VS Code 的 Python 问题九成是解释器没选对——三层模型里任何一层和其他两层失联都会以飘红或报错的形式喊出来。排查时永远先问三个问题右下角选的是谁Pylance 扫描的是谁终端里跑的是谁——三者的答案应该是同一个。和 pip 排错那篇合起来看环境问题的解法从不在重装大法而在让每一层的归属关系显式化。pip 那篇的python -m pip锁定了安装目标这篇的python.defaultInterpreterPath锁定了分析目标——两条命令背后是同一个工程哲学归属不明的工具链永远比 bug 本身更危险。