提升Python开发效率的VSCode插件与配置清单

写 Python 这么多年，VSCode 的配置文档翻来覆去看过好几套，但真正能把「开箱即用」做到不卡壳的，其实就那么几个关键开关。下面直接上结论，再拆开讲怎么落地。

先说第一件事：Pylance 必须显式指定为语言服务器，Black 得设为默认格式化器，否则后面所有自动化操作都跑偏。配置的完整链条是四个 settings.json 项："python.languageServer": "Pylance"、"python.formatting.provider": "black"、"editor.formatOnSa ve": true、"editor.codeActionsOnSa ve": {"source.organizeImports": true}。另外，跨目录导入引起的红色波浪线，要靠 "python.analysis.extraPaths" 解决。

这四行缺一不可，少一个就可能在保存时格式化失效或者 import 报红。下面逐个拆解。

Python 官方插件 + Pylance 是语言支持的底线

只装 ms-python.python 远远不够——它默认启用的是旧版语言服务器，类型提示弱、跳转卡顿，typing 模块里的泛型甚至无法正确识别。必须搭配 Pylance（Microsoft 官方维护），并且在 settings.json 里显式开启：

• "python.languageServer": "Pylance"
• "python.analysis.typeCheckingMode": "basic"（大型旧项目可以用 "off" 避免噪音）
• "python.analysis.extraPaths": ["./src", "./tests"]（专门对付跨目录 import 报红）

最常见的翻车现场：from mypackage import module 整行标红，但命令行跑起来一切正常。问题九成出在 extraPaths 没配，或者路径写成了 "src/"（末尾多一个斜杠就会导致识别失败）。

保存即格式化：black + isort + auto-sa ve 的真实链路

光打开 editor.formatOnSa ve 只能触发格式化，import 排序完全不会动。真正起作用的其实是三个设置协同工作：

• "python.formatting.provider": "black"
• "editor.codeActionsOnSa ve": {"source.organizeImports": true}
• "editor.formatOnSa ve": true

这里面有个容易误解的地方：isort 插件本身不负责自动触发，它靠 VSCode 内置的 source.organizeImports 动作来调用。如果保存后 import 没整理，先去检查 Python 插件的 python.editor.codeActions 是否被关闭了（默认开启，一般不用动）。

另外，Black 格式化单文件时要做 AST 解析，文件稍大就会有一两秒的卡顿，习惯就好——总比手动改缩进强得多。

调试配置别硬背 launch.json，用命令面板更快

手写 launch.json 太容易遗漏关键字段了，比如忘了写 "console": "integratedTerminal"，调试时输出直接消失。更稳的办法是走命令面板：

• 打开任意 .py 文件
• Ctrl+Shift+P → 输入 Python: Configure a debug configuration
• 选择 Python File，VSCode 会自动生成带注释的完整配置

关键区别："program": "${file}" 表示调试当前文件，而像 "module": "torch.distributed.run" 这种模块启动，必须选 Python Module 模板，不能复用文件模板。

还容易踩的坑包括：env 字段写成了数组而不是对象，或者 "PYTHONPATH" 的值带了末尾斜杠（比如 ./src/），都会让导入失败。

远程开发与虚拟环境识别失效的典型原因

在 WSL 或 SSH 远程连接后，用 Python: Select Interpreter 找不到虚拟环境，往往不是路径写错了，而是下面三个原因之一：

• 远程机器上根本没装 pip 或 venv（Ubuntu 默认不安装 python3-venv）
• ./venv/bin/python 文件没有执行权限（跑一下 chmod +x 就能解决）
• VSCode Remote 插件没启用，或者连接后没有重新加载窗口——看右下角 Python 解释器状态栏如果是灰色，说明加载失败

要验证到底加载了没有，最简单的方式：在远程终端里执行 ./venv/bin/python -c "import sys; print(sys.path)"，然后对比 VSCode 解释器详情页里显示的 sys.path。两边不一致，就说明 VSCode 没有正确识别这个虚拟环境。

最后补一句：python.linting.enabled 这个开关必须和 flake8 或 pylint 这类具体 linter 插件配合使用，单独打开只会冒出一堆“no linter selected”的警告。真正的效率提升，是让错误在括号还没敲完的时候就标出来，而不是等着运行时报 NameError。