VS Code + Python：开发环境优雅配置指南

引言

这是第一章的第 9 篇。前 8 篇我们把命令行工具链装齐了：解释器（第 2 篇）、venv（第 4 篇）、pip（第 5 篇）、REPL（第 6 篇）、规范工具（第 7 篇）、调试器（第 8 篇）。但真实工程中，你每天对着的不是命令行，而是一个编辑器——代码在那里被书写、补全、检查、运行、调试。工欲善其事，必先利其器，本文解决的就是这个问题：把 VS Code 配成一个专业的 Python 开发环境。

读者应先掌握：会用第 4 篇的 venv 创建虚拟环境，会第 7 篇的 flake8/black 基本命令，理解第 8 篇调试的 n/s/c 概念——因为本文的图形化调试，就是把这些命令行概念搬上了界面。本文面向 VS Code 桌面版（当前主流版本），配置内容全部基于真实扩展与真实文件格式，不涉及任何虚构功能。

为什么是 VS Code：编辑器与扩展的架构

VS Code（Visual Studio Code）是微软出品的免费开源编辑器，基于 Electron（用 Web 技术构建桌面应用）打造。它之所以是 Python 社区使用率最高的编辑器之一，关键在于它的扩展机制：核心编辑器只提供通用能力（文件编辑、命令面板、终端），语言支持全部由扩展（extension）按需加载。这意味着 Python 工具链的每一次进化（新调试器、新格式化器）都以独立扩展的形式迭代，互不阻塞。

对 Python 而言，有三款官方扩展值得第一时间安装，它们由 VS Code 的 Python 团队维护：

ms-python.python（Python）：核心扩展，提供智能补全、运行/调试入口、解释器管理、交互式窗口；它自动管理调试器（debugpy）的安装；
ms-python.vscode-pylance（Pylance）：类型检查与补全引擎，基于微软自家的静态类型分析技术，提供悬停文档、签名提示、跳转定义；
ms-python.debugpy（Python Debugger）：第 8 篇 pdb 的图形化版本就是它实现的，基于 debugpy——一个实现了调试适配协议（DAP）的调试器，也是 VS Code 调试 Python 的标准底层。

装好这三件，就等于把第 7 篇的 pycodestyle/flake8/black 搬进编辑器。我们沿用手动安装法（也可以直接在扩展面板搜索安装，效果相同）：

code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension ms-python.debugpy

（code 是 VS Code 的命令行入口，安装 VS Code 后自动进入 PATH。也可以在编辑器中按 Ctrl+Shift+P 打开命令面板，输入 “Extensions: Install Extensions” 后搜索安装——命令面板 Ctrl+Shift+P 是 VS Code 所有操作的统一入口，值得现在就记住。）

关键机制：解释器的选择与 Python 环境的绑定

VS Code 的 Python 支持围绕一个核心概念：当前解释器（interpreter）。所有补全、运行、调试行为都绑定到这个解释器。前面第 4 篇我们已经为项目创建了虚拟环境（例如 venv/ 或 .venv/），VS Code 需要明确选择这个 venv 里的解释器，而不是系统全局 Python——否则会出现”终端能跑、编辑器里 ImportError”的精分现场（这个坑我们在易错点详细展开）。

选择方式是交互式的：Ctrl+Shift+P 打开命令面板，输入 “Python: Select Interpreter”，在弹出的列表中选中你的虚拟环境（列表里会标注 ('.venv': venv) 字样，Ctrl+P 输入 Python: Select Interpreter 一样可达）。选中后，VS Code 会在窗口状态栏显示解释器版本。这一步也会自动生成 .vscode/settings.json，把选择记进项目。

若要理解”选择”背后发生了什么，可以看这个文件。.vscode 目录位于项目根下，其中的 settings.json 是工作区级配置，优先级高于用户级配置，跟随项目走（整个目录应该提交进版本库与队友共享）。一个典型的 Python 工作区配置长这样：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
  "python.terminal.activateEnvironment": true,
  "python.analysis.typeCheckingMode": "basic",
  "editor.formatOnSave": true,
  "python.formatting.provider": "none"
}

逐条说明：python.defaultInterpreterPath 指定默认解释器路径（Windows 下虚拟环境解释器位于 .venv/Scripts/python.exe，Linux/macOS 位于 .venv/bin/python）；python.terminal.activateEnvironment 让集成终端自动激活虚拟环境；python.analysis.typeCheckingMode 控制 Pylance 的类型检查严格度（basic 是很实用的起步档）；editor.formatOnSave 保存即格式化；最后一条 python.formatting.provider 设为 none 是为了把格式化交给第 7 篇的 black 扩展 ms-python.black-formatter（2023 年起官方推荐以独立扩展代替旧的 python.formatting.provider 内置选项）。注意：不同 VS Code 版本与扩展版本对配置项的兼容性会变，所以装好扩展后最可靠的做法仍是：在命令面板输入 “Preferences: Open Settings (JSON)” 后，带着具体版本号搜官方文档核对——文档永远比记忆新。

与 settings.json 齐名的第二个配置是 launch.json，它保存调试配置。点击左侧”运行和调试”图标（或 Ctrl+Shift+D），选择”创建 launch.json”，VS Code 会基于 debugpy 生成模板。调试一个当前打开的脚本，配置如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 调试当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    }
  ]
}

解读："type": "debugpy" 是当前官方推荐的调试器类型（旧教材里的 "python" 已弃用，新版扩展会引导迁移）；"request": "launch" 表示”启动一个新进程来调试”（调试正在运行的进程用 "attach"，那是后话）；"program": "${file}" 表示调试当前编辑器打开的文件——${file} 这类 ${变量} 是 VS Code 的变量替换语法，除此之外还有 ${workspaceFolder}（项目根目录）等；"justMyCode": true 让调试器跳过第三方库的内部代码，只停在你自己的代码里（调试时不被几十层依赖库干扰的利器）。

调试工作台：把 pdb 的 n/s/c 图形化

配置好 launch.json 后，在第 8 篇的 scores.py 里点击行号左侧的沟槽（gutter）打一个红点——这就是断点，对应 pdb 的 b 行号；按 F5 启动调试，对应 c。程序在断点处停住后，工作台比命令行多出几样东西：

调试工具栏：继续（F5）、单步跳过（F10，对应 pdb 的 n）、单步进入（F11，对应 s）、单步跳出（Shift+F11，对应 r）、重启（Ctrl+Shift+F5）、停止（Shift+F5，对应 q）；
变量面板（VARIABLES）：自动列出当前帧的局部变量与全局变量，鼠标悬停在上面的变量上同样能看到当前值——p 变量 的活儿它全干了，而且是实时更新的；
监视面板（WATCH）：添加 scores[i + 1] 这类表达式，每次停下都自动求值；
调用堆栈面板（CALL STACK）：对应 pdb 的 w，点击任意一帧即可跳转查看。

与 pdb 相比，图形化调试的额外红利是条件断点：在断点红点上右键选”编辑断点”，填入 i == 2，程序只在 i 等于 2 时才停下——这正是第 8 篇练习 4”循环里不想每轮都停”的工程化解法。这套快捷键与面板是 VS Code 调试任意语言的家底，学一次受用终身。

除了调试，还有两个日常效率点值得顺手掌握。第一，Ctrl+打开集成终端，它自动使用你在settings.json` 里指定的解释器环境，第 4 篇 venv 的激活在此无感完成。第二，Python 扩展的交互式窗口：选中几行代码，按 Shift+Enter，代码会送到”Python Interactive”窗口里执行——这是第 6 篇 REPL 的图形化形态，也是第 10 篇 Jupyter 在 VS Code 里的入口。

入口即出口：跑通一个最小闭环

为避免”配置了但不知道起没起作用”，建议按以下顺序做一次完整闭环验证。第一步，项目目录创建虚拟环境并安装第 7 篇的工具（以下为真实可执行命令）：

python -m venv .venv
.venv/Scripts/python -m pip install flake8 black debugpy

第二步，按上文完成解释器选择，确认状态栏出现 .venv 与 Python 版本号。第三步，新建 demo.py，故意写一行不规范代码（例如 x=1）与一个断点：保存时观察 black 是否自动格式化掉 x=1 的空格问题，F5 后观察变量面板是否如实显示 x 的值。三个现象对上了，环境就绪。用一条命令快速自检调试基础是否可用（debugpy 可直接被 Python 导入，说明调试器本体正常）：

.venv/Scripts/python -c "import debugpy; print(debugpy.__version__)"

输出形如 1.8.21 的版本号即正常（版本随安装时间而变）。

易错点与陷阱

1. 编辑器”看不到”虚拟环境里的包。 全套配置里最高发的坑：终端里 pip install 的包能 import，VS Code 里却 ModuleNotFoundError；或者反过来。原因只有一个——解释器选错了。VS Code 的补全、运行、调试全部跟随状态栏里那个解释器；如果它指向全局 Python，就看不到 venv 里装的包。对策：养成习惯，新建项目先 Select Interpreter 再写代码，状态栏解释器必须带 .venv 标识。顺带一提，.vscode/settings.json 里的 python.defaultInterpreterPath 用的是”默认路径”，若无此文件或路径失效，VS Code 会退回全局解释器——所以这个文件一定要提交进版本库。

2. 配置用”记忆”而不是”版本”。 VS Code 的 Python 工具链演进很快：python.linting.flake8Enabled 这类旧配置项在 2023 年后被独立扩展取代；launch.json 的 "type": "python" 被 "type": "debugpy" 取代。老教程的配置很可能在新版本里静默失效（选项不报错，但不起作用）。对策：配置文件里凡是”记忆中的选项”，先在命令面板搜到对应设置项再写，或直接在设置 UI 里点选（UI 里点出来的配置一定是当前版本支持的）；借助扩展面板查看扩展是否提示”已弃用”。

3. justMyCode 关掉反而更好调试？别急着关。 新手看到异常堆栈里一堆 site-packages 的帧，就想去掉 justMyCode: true 看看”底层”——结果是把调试器拖进依赖库的泥潭。默认 true 是让调试聚焦你自己的代码；真需要排查三方库内部（例如怀疑 pandas 内部出错）时，再去切换也不迟，并且随后记得改回来。同理，"console": "integratedTerminal" 与 "internalConsole" 会改变 print 输出去向，配置调试时先把这两个字段搞明白再动。

4. 扩展装了一堆，功能互相打架。 同时安装 black 扩展与 autopep8 扩展、flake8 与 ruff 扩展并存，可能造成”保存时格式被来回改写”或”同一处代码两种样式报错”。规范的做法是第 7 篇讲过的”单一工具落地”：格式化只留 black，检查只留 flake8（或只留 ruff），其余禁用；formatOnSave 打开，lint 打开，样式冲突问题自然消失。

小结

本文完成了一次性的”编辑器基建”：VS Code 通过扩展机制承载 Python 支持，官方三件套 ms-python.python（核心）、Pylance（类型与补全）、debugpy（图形化调试）是标配；核心机制是解释器绑定——Select Interpreter 把补全、运行、调试统一到第 4 篇创建的 venv；工作区配置由 .vscode/settings.json（格式化、解释器路径、类型检查）与 launch.json（调试器类型 debugpy、${file} 变量、justMyCode）两张文件承载。调试工作台把第 8 篇 pdb 的命令全部图形化：F5 启动（c）、F10/F11（n/s）、变量与监视面板（p）、调用堆栈（w），外加条件断点这一命令行没有的增值。避开四个坑：解释器选错导致包不可见、记忆过时配置、乱关 justMyCode、多工具叠加冲突。下一篇文章是本章最后一篇——把 Jupyter Notebook 的交互式工作台装进你的工具箱，学会用 notebook 做数据探索。

练习与思考题

动手完成”最小闭环”：新项目建 venv、装 black/flake8/debugpy、选解释器、写 demo.py、保存自动格式化、F5 断点调试，四个环节逐一确认现象。写清每个环节”现象正常”的标志分别是什么。（答案导向：状态栏解释器、保存即改写、F5 停红点、变量面板有值。）
在你的项目里查看 .vscode/settings.json，逐一说出每个配置项的用途；如果 .vscode 不存在，说出为什么它可能没有生成以及如何手动创建。（答案导向：Select Interpreter 会自动生成；没有就自己建目录写 JSON。）
对比第 8 篇 pdb 命令与 VS Code 调试面板的对应关系，写出至少 5 组”命令 → 界面操作”的映射（如 b 行号 → 点红点）。（答案导向：n→F10、s→F11、p→变量面板/悬停、w→CALL STACK、q→Shift+F5、c→F5。）
思考题：launch.json 里 "program": "${file}" 与 "program": "${workspaceFolder}/demo.py" 的区别，以及各自适合什么使用场景。（答案导向：前者调试当前打开的文件、灵活；后者固定调试某入口文件、适合固定入口的项目。）