根本原因是linux内核yama模块默认ptrace_scope=1，禁止debugpy对非子进程ptrace，导致其静默退出；验证方法包括检查ptrace_scope值、debugpy进程与端口监听状态；推荐修复方案为临时修改ptrace_scope、授予cap_sys_ptrace权限或改用attach模式。
为什么 Python 调试器在 Linux 上卡在 “Waiting for debugger to attach”
根本原因不是 debugpy 没启动，而是它启动后尝试用 ptrace 检查或控制子进程时被内核拒绝——VSCode 的 Python 调试流程依赖 debugpy 在后台 fork+exec 子进程并注入调试逻辑，这一步需要 ptrace 权限。当 /proc/sys/kernel/yama/ptrace_scope 为 1（Ubuntu/Debian/Fedora 默认值）时，非子进程的 ptrace 调用直接失败，debugpy 静默退出，VSCode 就一直等不到连接。
如何快速验证是不是 ptrace 权限问题
别急着改配置，先确认现象是否匹配：
- 终端里手动运行
python -m debugpy --listen 127.0.0.1:5678 your_script.py，观察是否立即退出、无日志、也无端口监听 - 执行
cat /proc/sys/kernel/yama/ptrace_scope，输出是1或2 - 用
ss -tuln | grep :5678查不到监听，但ps aux | grep debugpy也看不到进程 - VSCode 控制台只显示
Waiting for debugger to attach...，几秒后断开，无错误堆栈
三种修复方式，按风险和适用场景排序
不推荐直接设 ptrace_scope=0（开放所有 ptrace），生产环境更不能这么干。优先选以下方案：
-
临时放开（调试用）：运行
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope，仅当前会话生效；重启后恢复 -
授予权限（推荐）：对 VSCode 启动的
code进程或debugpy所在 Python 解释器加CAP_SYS_PTRACE，例如：sudo setcap cap_sys_ptrace+ep $(readlink -f $(which python3)) -
换 attach 模式（最安全）：改
launch.json为"request": "attach"，先手动跑python -m debugpy --listen 127.0.0.1:5678 your_script.py，再让 VSCode 连上去——此时debugpy是父进程，ptrace 不受限
WSL2 和容器环境下要额外注意
WSL2 默认继承宿主机的 yama 设置，但 setcap 对 Windows 下的 Python 可执行文件无效；容器里则需确保 securityContext.capabilities.add 包含 SYS_PTRACE，且 ptrace_scope 在容器内也被设为 0 或通过 docker run --cap-add=SYS_PTRACE 显式授权。单纯在宿主机改 ptrace_scope 对容器内进程无效。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
