vscode调试器不执行python代码，只转发请求：它作为dap客户端，依赖独立启动的debugpy进程执行代码、处理断点；断点灰色或调试失败通常因debugpy未就绪、解释器路径不一致、launch.json中program/module/cwd配置错误或pathmappings缺失所致。
VSCode调试器不执行Python代码，只转发请求
VSCode 本身完全不解析、不运行、不中断 Python 代码——它只是 DAP（Debug Adapter Protocol）客户端。真正执行 python 进程、处理断点、管理调用栈的，是独立启动的 debugpy（或其他适配器）。你看到的“开始调试”按钮，本质是 VSCode 启动一个子进程：python -m debugpy --listen 127.0.0.1:5678 --wait-for-client ...，然后通过 stdin/stdout 与之建立 JSON-RPC 通信。
这意味着：如果你在终端手动运行 debugpy 并连上 VSCode，效果完全一致；反过来，如果 debugpy 启动失败（比如路径错、权限不足、端口被占），VSCode 就只会卡在“正在启动调试器…”或报 Could not load module 'debugpy'，而不是抛 Python 异常。
- 调试器崩溃 ≠ 你的代码崩溃：
debugpy进程挂了，VSCode 会显示“调试会话已终止”，但目标 Python 程序可能早已退出或卡死 - 断点灰色 = DAP 层未就绪：常见于
debugpy没成功 attach、launch.json 中program路径不存在、或文件没保存（VSCode 发送的是磁盘路径，不是编辑器缓存） - 修改 launch.json 后必须重启调试会话：DAP 连接是一次性建立的，参数变更不会热更新
Python解释器路径决定 debugpy 的运行环境
VSCode 调试时用的不是你终端里 which python 的结果，而是 launch.json 中显式指定的解释器，或全局选中的那个——这个解释器必须能 import debugpy。很多人装了 debugpy 却断点不生效，就是因为：VSCode 界面右下角显示的是 /usr/bin/python3，而 launch.json 里写了 "python": "./venv/bin/python"，两者不一致，导致 debugpy 在错误环境里被加载（或根本找不到）。
- 检查方式：调试启动瞬间，在集成终端里执行
ps aux | grep debugpy，看其父进程的python路径是否与预期一致 - 虚拟环境必须提前安装
debugpy：./venv/bin/python -m pip install debugpy，Python 扩展不自动帮你装 - Conda 环境更易出问题：conda 的
python可执行文件是 shell wrapper，某些旧版debugpy无法正确识别其 site-packages，建议用conda install -c conda-forge debugpy
launch.json 的 program/module/cwd 三者必须协同
VSCode 不靠文件名或右键菜单猜你怎么运行 Python，全靠 launch.json 里的三个字段组合。写错任意一个，就可能导入失败、相对路径错乱、断点加载失败。
-
"program": "${file}"→ 直接执行该文件，此时cwd决定sys.path[0]和相对导入起点；若项目有from .utils import x，cwd必须设为包根目录 -
"module": "http.server"→ 等价于python -m http.server，此时program字段必须删除或留空，否则冲突；cwd影响模块搜索路径，但不改变-m的入口逻辑 -
"args": ["--port", "8000"]是唯一传参方式，写进program值里（如"program": "${file} --port 8000"）会导致整个字符串被当做一个文件路径去查找
远程调试时，debugpy 必须在远端运行且端口可通
用 Remote-SSH 调试 Python，不是本地 VSCode 连远端 python，而是本地 VSCode 连远端 debugpy。所以关键不在“能否 ssh 登录”，而在“远端 debugpy 是否监听、防火墙是否放行、本地能否 telnet 通那个端口”。
- 典型配置：
"host": "your-server","port": 5678,"pathMappings": [ { "localRoot": "${workspaceFolder}", "remoteRoot": "/home/user/project" } ] - 路径映射（
pathMappings）不是可选项：VSCode 断点位置是本地文件路径，远端debugpy看到的是远端路径，必须靠这个映射对齐，否则断点永远灰色 - 别用
localhost当 host：远端debugpy绑定的是127.0.0.1，只能本机连；要让本地 VSCode 连，得绑定0.0.0.0或具体 IP，并确保远端防火墙开放该端口
debugpy 进程的生命周期和环境隔离性——它不是 VSCode 的线程，而是独立子进程，有自己的 Python 解释器、PATH、LD_LIBRARY_PATH 和当前工作目录。任何假设“它和我终端里跑的一样”的操作，基本都会踩坑。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
