安装Python扩展后必须手动配置python.defaultInterpreter，VSCode不会自动识别系统Python；调试应优先用module模式而非file模式；格式化需禁用默认工具，改用black+isort；终端需设为登录shell以加载conda/pyenv环境。
安装 Python 扩展后必须配置 python.defaultInterpreter
VSCode 不会自动识别系统中已安装的 Python 解释器，即使你已通过 pyenv、conda 或系统包管理器安装了多个版本。不手动指定，python 命令可能指向错误版本，导致调试失败、pip 安装包不生效、或 import 报错。
操作方式：按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Python: Select Interpreter，从列表中选择目标解释器路径（如 ~/miniconda3/envs/myenv/bin/python 或 C:\Users\Xxx\anaconda3\envs\py311\python.exe）。该设置会写入工作区 .vscode/settings.json 的 python.defaultInterpreter 字段。
- 若项目使用
venv，务必在激活虚拟环境后运行该命令，否则 VSCode 可能选中全局 Python - 多人协作时，建议把
.vscode/settings.json加入.gitignore，避免硬编码本地路径 - 在远程开发（SSH / WSL / Containers）场景下，需在对应环境中重复执行该步骤，本地设置不继承
调试时 launch.json 的 module 模式比 file 更可靠
直接调试脚本文件（"request": "launch", "type": "python", "program": "main.py"）在导入相对模块或使用 if __name__ == "__main__" 逻辑时容易出错——尤其当项目结构含 src/ 目录或需要 -m 方式运行时。
推荐改用模块模式：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: mypackage",
"type": "python",
"request": "launch",
"module": "mypackage.main",
"console": "integratedTerminal",
"justMyCode": true
}
]
}该配置等价于终端执行 python -m mypackage.main，能正确解析 sys.path 和包层级，避免 ModuleNotFoundError。
-
module字段值必须是合法的 Python 模块名（不含.py后缀，路径用点分隔） - 确保当前工作目录（
cwd）为包的父目录，或已在PYTHONPATH中包含该路径 - 如果使用 Poetry 或 PDM，需确认
pyproject.toml中的[project]名称与模块名一致，否则-m无法定位
禁用默认格式化器，改用 black + isort 组合
VSCode 自带的 Python 格式化器（autopep8 或 yapf）默认启用，但风格松散、不兼容现代工具链，且与 black 冲突——比如对多行字符串、类型注解缩进的处理逻辑完全不同，频繁切换会导致 Git diff 爆炸。
立即学习“Python免费学习笔记（深入）”；
应在用户或工作区设置中显式禁用并接管：
"python.formatting.provider": "none",
"editor.formatOnSave": true,
"[python]": {
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": true
}
},
"python.formatting.blackArgs": ["--line-length=88"],
"python.sortImports.args": ["--profile", "black"]
-
blackArgs和sortImports.args必须与项目根目录下的pyproject.toml中配置保持一致，否则本地格式化结果和 CI 检查不一致 - 若使用 pre-commit，确保
.pre-commit-config.yaml中black和isort版本与 VSCode 插件调用的 CLI 版本相同 - 不要勾选设置里的 “Format on type”，它会在键入中途触发重排，干扰代码逻辑输入
终端未加载 shell 配置（如 ~/.zshrc）导致 conda activate 失败
VSCode 内置终端默认以非登录 shell 启动，不会读取 ~/.zshrc 或 ~/.bashrc，因此 conda 命令不可用，或 poetry 环境变量缺失，表现为 Command 'conda' not found 或 poetry: command not found。
解决方法：修改 VSCode 设置 terminal.integrated.profiles.<os></os>，强制以登录 shell 启动：
"terminal.integrated.profiles.linux": {
"zsh": {
"path": "zsh",
"args": ["-l"]
}
},
"terminal.integrated.defaultProfile.linux": "zsh"
macOS 和 Windows 同理，分别设 zsh -l 或 pwsh -login。注意 -l 参数必须小写，且不能与 --init-file 混用。
- 该问题在 WSL 环境下尤为常见，因为 WSL 默认 shell 是
bash，但用户常改用zsh并在~/.zshrc中初始化 conda - 若使用
pyenv，同样依赖 shell 配置中的export PATH和eval "$(pyenv init -)"，不加-l就无法生效 - 重启 VSCode 终端（关闭再打开新 tab）才能使配置生效，仅重启进程无效
