直接安装Microsoft官方Python扩展（ms-python.vscode-python）即可调试，无需额外安装独立“Python调试工具”；该扩展内置调试器，但必须重启VSCode、正确选择Python解释器路径，并在.py文件中按F5才能自动生成launch.json启动调试。
直接装 Python 扩展就能调试，不需要额外装“Python调试工具”这个独立组件。 VSCode 的 Python 调试能力由 ms-python.python（现名 ms-python.vscode-pyton）扩展提供，它内置了调试器、语言服务器和运行时集成。所谓“安装调试工具”，本质是正确安装并激活这个扩展，并配好解释器路径。
确认已安装 Microsoft 官方 Python 扩展
很多人卡在第一步：以为装了 VSCode 就能调试 Python，其实缺的是这个扩展。它不是系统级工具，而是 VSCode 内部的插件。
- 打开 VSCode，在左侧活动栏点扩展图标（或按
Ctrl+Shift+X） - 搜索
Python，认准发布者为Microsoft、ID 是ms-python.python（2026 年起新版显示为ms-python.vscode-python） - 点击 Install，安装后必须重启 VSCode 或点击 Reload 按钮生效 —— 不 reload，
launch.json生成、断点、变量查看等功能全都不工作 - 装完后，状态栏右下角会显示当前 Python 解释器路径，例如
Python 3.10.12 (/usr/bin/python3)；如果显示Select interpreter，说明还没选解释器，调试必然失败
必须手动选择 Python 解释器路径
VSCode 不会自动猜你用哪个 python，尤其当你装了多个版本（系统自带、pyenv、conda、venv），选错就等于调试器启动时找不到入口模块。
- 按
Ctrl+Shift+P打开命令面板，输入Python: Select Interpreter回车 - 列表里会出现所有可识别的解释器，优先选带明确路径的项，比如：
./venv/bin/python（项目虚拟环境）、~/miniconda3/envs/myenv/bin/python（conda 环境）、/usr/bin/python3.12（系统全局） - 避免选
Python Path为空或标着(undefined)的条目 —— 这类通常只是占位符，无法真正启动调试器 - 选完后，VSCode 会在当前工作区根目录下生成
.vscode/settings.json，内容类似：{"python.defaultInterpreterPath": "./venv/bin/python"}，这是调试行为的依据
首次调试时自动生成 launch.json 的关键条件
按 F5 启动调试前，VSCode 需要一个有效的 launch.json。它不会凭空生成，必须满足两个前提：
立即学习“Python免费学习笔记（深入）”；
- 当前打开的文件是
.py文件（比如main.py），且该文件处于编辑器激活状态（光标在里面） - 已成功选定解释器（上一步已完成），否则弹出的环境选择菜单里看不到
Python选项，只能看到None或报错No debug configuration found - 选中
Python File模板后，生成的.vscode/launch.json默认包含：{ "configurations": [ { "name": "Python: Current File", "type": "python", "request": "launch", "module": "python", "justMyCode": true, "cwd": "${fileDirname}", "args": [], "env": {} } ] }注意"type": "python"—— 这才是调用 Python 调试器的核心标识，不是cppdbg或node
常见失败现象与对应修复动作
调试启动失败时，别急着重装扩展，先看终端输出和弹窗提示，90% 的问题都集中在以下三处：
-
ModuleNotFoundError: No module named 'ptvsd'或Could not find a debugger backend：这是旧版扩展遗留问题，说明你装的是已废弃的ptvsd调试后端。解决方法：卸载所有非 Microsoft 的 Python 相关扩展（如Python for VS Code、PyDebug），确保只留ms-python.vscode-python，然后重启 VSCode - 按
F5后终端一闪而过、无任何输出：检查launch.json中"cwd"是否指向了错误目录，或者"args"里传了非法参数（如含空格未加引号）；更常见的是当前文件没保存（launch.json默认调试当前文件，未保存 = 临时文件路径无效） - 断点灰色不可用（显示 “Breakpoint ignored because generated code not found”）：说明调试器没加载到源码映射，通常是解释器路径指向了打包后的可执行文件（如
poetry run python包装脚本），而非真实python可执行文件。应改用venv/bin/python这类直连路径
最易被忽略的点是：调试依赖解释器本身是否支持调试协议。某些精简版 Python（如 Alpine Linux 上的 python-alpine）或自编译去掉 _debug 模块的版本，会导致 debugpy 启动失败，但错误日志藏在 Output 面板的 Python 子标签里，不主动翻就永远看不到。
