直接attach进容器调试失败，根本原因是容器内python进程未主动监听调试端口且缺乏debugpy等依赖；必须确保容器中安装debugpy、绑定0.0.0.0:5678、映射端口并正确配置launch.json的pathmappings与remoteroot路径。
为什么直接 attach 进容器调试会失败
VS Code 的 Python 扩展默认通过 ptvsd 或 debugpy 启动调试器，但远程容器里若没装对应调试器、没暴露调试端口、或 Python 路径不一致，attach 就会卡在 “Waiting for debugger connection…”。常见错误信息是：Connection refused 或 ModuleNotFoundError: No module named 'debugpy'。
关键点不是“能不能连”，而是“谁启动调试服务”——必须由容器内 Python 进程主动监听并等待 VS Code 连接，而不是反过来。
- 容器里必须安装
debugpy（推荐 1.6+，兼容性更好）：pip install debugpy - 启动命令需显式调用
debugpy，例如：python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m your_module -
--listen必须绑定0.0.0.0（不是127.0.0.1），否则宿主机无法访问 - Docker 运行时要加
-p 5678:5678，且确保防火墙/云服务器安全组放行该端口
如何配置 launch.json 让 VS Code 正确 attach 到容器
不要用 python 类型的 launch 配置去跑容器——那是本地执行。要用 python: attach 模式，并严格匹配容器内调试器参数。
典型 .vscode/launch.json 片段：
{
"configurations": [
{
"name": "Python: Remote Attach",
"type": "python",
"request": "attach",
"connect": {
"host": "localhost",
"port": 5678
},
"pathMappings": [
{
"localRoot": "${workspaceFolder}",
"remoteRoot": "/app" // 必须和容器内代码路径完全一致
}
],
"justMyCode": true
}
]
}
注意几个易错细节：
-
remoteRoot是容器内的绝对路径，比如 Dockerfile 里WORKDIR /app，那这里就不能写/src - 如果容器用了多层目录挂载（如
-v $(pwd):/app/src），remoteRoot得写成/app/src -
justMyCode设为false可调试第三方库，但会显著拖慢断点响应，一般保持true
用 devcontainer.json 实现一键打开即调试
比手动 attach 更稳的方式：把开发环境定义进容器，让 VS Code 直接以容器为工作区。这样 Python 解释器、依赖、调试器全在容器里，路径和端口自动对齐。
在项目根目录建 .devcontainer/devcontainer.json：
{
"image": "python:3.11-slim",
"forwardPorts": [5678],
"customizations": {
"vscode": {
"extensions": ["ms-python.python"]
}
},
"postCreateCommand": "pip install debugpy"
}
然后按 Ctrl+Shift+P → Dev Containers: Reopen in Container。之后所有操作（包括运行 launch.json）都在容器上下文中执行，remoteRoot 可直接用 ${workspaceFolder}，基本不用手调路径映射。
- 如果已有 Docker Compose 环境，可用
dockerComposeFile+service字段替代image -
forwardPorts是关键——它自动处理端口映射和本地转发，比手动-p更可靠 -
postCreateCommand保证每次重建容器都装上debugpy，避免忘记安装导致 attach 失败
断点不命中？先检查这三件事
最常被忽略的是路径同步问题：VS Code 认为断点在 /Users/me/project/main.py，而容器里实际加载的是 /app/main.py，但 pathMappings 没配对，结果断点变空心圆。
- 在容器里运行
python -c "import main; print(main.__file__)"，确认实际加载路径 - 在 VS Code 调试控制台执行
debugpy.log_to("/tmp/debugpy.log")，看日志里是否报Source map mismatch - 如果用了 symlink 或 volume 挂载，检查容器内
ls -l /app输出，确保软链目标路径也被正确映射
另外，debugpy 对某些异步框架（如 FastAPI 的 uvicorn）需要额外参数：--wait-for-client 必须放在 --listen 后面，顺序错了会导致进程不挂起、断点直接跳过。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
