4.1 Python 工位整备

4.1 Python 工位整备

本节摘要：Python 整备四步走：主扩展与语言服务器打底、虚拟环境选择、代码检查与格式化按新架构接分离扩展、测试与调试收尾。重点消化"检查器换代"——旧的集成式设置已成历史，检查与格式化各自归位到专用扩展。整备完的 Python 工位，从解释器到测试面板全程在编辑器内闭环。

后端专区从 Python 开工，因为它最能说明这轮升级的通用章法：语言装备从来不是"装一个插件完事"，而是扩展、解释器、工具链三层的组合整备。这一节承接第 2 章立下的分工原则（格式化管排版、检查管对错），把 Python 工位按新架构走一遍，其中"检查器换代"一段是理解插件生态演化的关键案例。

第一层：主扩展与语言服务器

Python 主扩展（官方出品）是整备的地基：装上它，状态栏出现解释器选择器，命令面板里出现环境相关的全套命令。它搭档的语言服务器负责补全、类型推断、诊断的重活——新装机器上建议确认语言服务器用的是高性能实现：

{
  "python.defaultInterpreterPath": "python3",
  "python.terminal.activateEnvironment": true,
  "python.languageServer": "Pylance"
}
​

解释器选择是 Python 工位的第一件正事：状态栏点选，或命令面板走"选择解释器"。选定后，补全、诊断、终端里激活的环境、调试用的运行时全部对齐到同一个环境——这个"四对齐"是排查"为什么编辑器不报错但终端跑不起来"类问题的第一检查点。

第二层：虚拟环境

Python 项目的依赖隔离靠虚拟环境，工位上的规矩是"一项目一环境"：项目根下建环境目录，解释器选择器指过去，扩展面板里该环境一目了然。环境建好后，主扩展在终端里自动激活它（上面的配置第二行），跑安装命令、起服务都在隔离环境内进行。团队协作时环境不入库（进忽略清单），人人本地各建，依赖清单入库——新人整备的次序因此固定：拉仓库、建环境、装依赖、选解释器，一步不乱。

第三层：检查器换代——从集成到分离

这是本节的重头。旧架构下，代码检查与格式化的开关都住在主扩展的设置里（一堆以检查器名字命名的键）；随着生态演进，这套设计被官方废弃，检查与格式化各自拆分到专用扩展：新一代高速检查器（一个工具同时管 lint 与部分格式化）、原厂格式化器、各家传统检查器的独立扩展。新架构的配置长这样：

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports.ruff": "explicit"
    }
  },
  "ruff.lint.enable": true,
  "ruff.format.args": ["--line-length", "100"]
}
​

换代的意义在于职责归位：主扩展只管语言服务与环境，检查器扩展只管规则诊断，格式化器扩展只管排版——这正是第 2 章分工原则在语种层面的落地。旧集成式设置残留的机器会看到"设置已废弃"的迁移提示，照提示走完迁移，然后按第 1 章的手续把旧设置键清场。

检查器的规则配置走项目里的配置文件（工具本体的配置，与编辑器无关），团队统一行宽、统一排除目录，编辑器端只是执行器——真相源在仓库，与第 2 章的排版配置同一哲学。

图 4-1：Python 工位装备栈分层

第四层：测试与调试收尾

测试走主扩展的测试面板：识别项目里的测试框架后，测试函数旁出现运行标记，侧栏树可单跑、可批量、可带覆盖率。调试走 2.4 节配好的会话系统，Python 的启动配置自带模板，模块启动与附加进程两档都要有：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    },
    {
      "name": "Python: 附加到进程",
      "type": "debugpy",
      "request": "attach",
      "processId": "${command:PickProcess}"
    }
  ]
}
​

一处新人常栽的坑：断点在第三方库代码里不生效，是因为默认只调试自己的代码——需要跟进库源码时再放开那个开关，平时保持开启可避免单步踩进依赖深处迷路。

台面实测：新项目的整备全程

从零走一遍：拉下仓库，建虚拟环境，选择解释器，装依赖；打开一个源文件，检查器立即标出两个未使用导入，保存时格式化器接管排版、导入自动整理同步执行；侧栏测试树全绿；调试当前文件，断点停住，变量区直接看到字典内容。全程没有碰过一次外部工具——这就是"整备"二字的目标状态。

坑点提醒

坑一，解释器漂移。 多环境机器上终端与编辑器各用各的解释器，症状是"编辑器没报错、一跑就崩"；先查状态栏的"四对齐"。坑二，新旧检查设置并存。 迁移没做干净时诊断行为诡异，把废弃键全数清除。坑三，环境目录误入版本控制。 环境体积巨大且机器相关，忽略清单要先行。

常见疑问快答

问：换项目后补全“失灵”，环境明明装好了？答：九成是解释器没切——新项目要重新走一遍“选择解释器”，四对齐才跟着切过去。状态栏的解释器显示是第一检查点，它的优先级高于一切排查动作。

问：新一代检查器与传统检查器，同时开行不行？答：规则重叠时诊断会重复甚至矛盾，建议主力只留一路：新项目上新一代高速检查器，老项目维持原有组合不动。并存过渡期最长一个迭代，之后按第 1 章手续退役旧装备。

替代方案

重型替代是专门的 Python 科学环境 IDE（数据处理场景有独到优势）；轻量替代是纯编辑器加命令行跑一切。编辑器整备路线的甜点在于与其他语种工位共用一套操作习惯——下一节的 Node.js 整备，你会发现通式完全一致。