返回首页
## 引言
这是第一章的第 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 搬进编辑器。我们沿用手动安装法（也可以直接在扩展面板搜索安装，效果相同）：
```bash
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 工作区配置长这样：
```json
{
"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 生成模板。调试一个当前打开的脚本，配置如下：
```json
{
"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 篇的工具（以下为真实可执行命令）：
```bash
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 导入，说明调试器本体正常）：
```bash
.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 做数据探索。
## 练习与思考题
1. 动手完成"最小闭环"：新项目建 venv、装 black/flake8/debugpy、选解释器、写 `demo.py`、保存自动格式化、F5 断点调试，四个环节逐一确认现象。写清每个环节"现象正常"的标志分别是什么。（答案导向：状态栏解释器、保存即改写、F5 停红点、变量面板有值。）
2. 在你的项目里查看 `.vscode/settings.json`，逐一说出每个配置项的用途；如果 `.vscode` 不存在，说出为什么它可能没有生成以及如何手动创建。（答案导向：`Select Interpreter` 会自动生成；没有就自己建目录写 JSON。）
3. 对比第 8 篇 pdb 命令与 VS Code 调试面板的对应关系，写出至少 5 组"命令 → 界面操作"的映射（如 `b 行号` → 点红点）。（答案导向：n→F10、s→F11、p→变量面板/悬停、w→CALL STACK、q→Shift+F5、c→F5。）
4. 思考题：`launch.json` 里 `"program": "${file}"` 与 `"program": "${workspaceFolder}/demo.py"` 的区别，以及各自适合什么使用场景。（答案导向：前者调试当前打开的文件、灵活；后者固定调试某入口文件、适合固定入口的项目。）