断点不命中需先确认launch.json是否启用attach模式：request必须为"attach"而非"launch"，并确保debugpy监听端口、pathMappings路径映射、--wait-for-client参数及解释器环境均正确配置。
断点不命中？先确认 launch.json 是否启用 attach 模式
VSCode 默认 launch 配置是 request: "launch"，它启动新进程；而监听已运行进程必须用 request: "attach"。如果错配成 launch，调试器会另起一个进程，自然无法捕获你手动启动的 Python 进程。
正确配置示例（保存在项目根目录 .vscode/launch.json）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Attach to Process",
"type": "python",
"request": "attach",
"connect": {
"port": 5678,
"host": "localhost"
},
"pathMappings": [
{
"localRoot": "${workspaceFolder}",
"remoteRoot": "."
}
]
}
]
}
-
port必须与 debugpy 启动时监听的端口一致（默认5678） -
pathMappings是关键：本地代码路径和远程/目标进程实际运行路径要对齐，否则断点位置无法映射 - Windows 用户若用 WSL 或远程 SSH，
host可能需改为"127.0.0.1"或具体 IP，避免 localhost 解析失败
debugpy 启动命令漏了 --wait-for-client？进程一闪而过
如果 Python 进程启动后立刻退出，大概率是 debugpy 没加 --wait-for-client 参数。这个参数让进程挂起等待 VSCode 连接，否则它直接执行完就结束，根本来不及 attach。
正确启动方式（在目标机器上执行）：
立即学习“Python免费学习笔记（深入）”；
python -m debugpy --listen 0.0.0.0:5678 --wait-for-client /path/to/your/script.py
-
-Xfrozen_modules=off建议加上，尤其在使用打包工具（如 PyInstaller）或某些容器环境里，否则 debugpy 可能读不到源码 -
--listen 0.0.0.0:5678表示监听所有网卡，但仅限可信网络；生产环境应限制为127.0.0.1 - 脚本路径必须是绝对路径，相对路径在不同工作目录下容易失效
变量面板全灰、断点变空心圆？检查解释器和路径上下文
空心断点（灰色圆圈）不是“没设好”，而是调试器压根没加载到对应文件——常见于解释器未识别或工作目录错位。
- 按
Ctrl+Shift+P运行Python: Select Interpreter，确认选中的是运行该脚本的实际环境（比如 venv/bin/python，而非系统全局 python3） - 在脚本开头加一行
import os; print(os.getcwd())，对比launch.json中是否设置了"cwd"，若没设，VSCode 默认用 workspace root，可能和 debugpy 实际工作目录不一致 - 如果用远程 SSH 连接，确保
.vscode文件夹在远程服务器的项目根目录下，而不是本地；VSCode 的 attach 配置只读远程的launch.json
多进程子进程断点失效？别指望 attach 自动覆盖
request: "attach" 只连接主进程，multiprocessing 子进程默认不会被 debugpy 注入——这和 subProcess: true 在 launch 模式下的行为完全不同。
- 若需调试子进程，必须在子进程启动前手动注入 debugpy，例如在子进程函数开头加：
import debugpy; debugpy.listen(5679); debugpy.wait_for_client()
并为每个子进程分配独立端口（如5679、5680），再分别 attach - 不要复用同一端口，debugpy 不支持多客户端共用一个 listen 端口
- spawn 启动方式比 fork 更可靠；fork 下 debugpy 可能无法拦截子进程初始化，尤其在 Linux 上
真正麻烦的不是配置多几行，而是子进程生命周期短——等你手动 attach 时它已经退出。所以带 --wait-for-client 的预注入，才是唯一可控的方式。
