先确认 launch.json 的 port 和 address 配置是否匹配容器网络模型：Node.js 需 --inspect=0.0.0.0:9229，Python 需 debugpy.listen(("0.0.0.0", 5678))，容器必须映射 -p 9229:9229 且监听地址为 0.0.0.0，VSCode 中 host 设 localhost、port 对应宿主映射端口，pathMappings 确保源码路径一致。
容器内调试时断点不触发，先确认 launch.json 的 port 和 address 配置是否匹配容器网络模型
VSCode 容器调试中断失败，90% 情况是调试器监听地址和端口没对上。本地开发时常用 "address": "localhost"，但进容器后，localhost 指的是容器内部回环，而 VSCode 运行在宿主机，必须让调试服务绑定到 "0.0.0.0" 才能被外部连接。
常见错误配置：
-
"address": "localhost"→ 容器内仅响应 127.0.0.1 请求，VSCode 连不上 -
"port": 9229正确，但没做端口映射或映射错宿主端口（比如-p 9229:9228） - Node.js 启动时漏了
--inspect=0.0.0.0:9229，只写--inspect默认绑定 127.0.0.1
用 docker run -p 映射调试端口时，必须确保容器内服务真实监听该端口
端口映射不是“魔法”，它只是把宿主机某端口的 TCP 流量转发过去。如果容器里根本没进程在监听目标端口，VSCode 就会报 Connection refused。
排查步骤：
- 进容器执行
netstat -tuln | grep :9229或ss -tuln | grep :9229，确认监听地址是*:9229或0.0.0.0:9229，不是127.0.0.1:9229 - 检查 Dockerfile 或启动命令：Node.js 要加
--inspect=0.0.0.0:9229；Python + debugpy 要用debugpy.listen(("0.0.0.0", 5678)) - 运行容器时确认
-p 9229:9229（非-p 9229单端口模式），且宿主机未被防火墙拦截
devcontainer.json 中的 forwardPorts 不等于端口映射，它只影响 VSCode UI 提示
forwardPorts 是 Dev Container 的便利功能，它会让 VSCode 自动帮你打开浏览器、提示端口可用，但它不替代 docker run -p 或 docker-compose.yml 里的实际端口暴露逻辑。
典型误区：
- 只在
devcontainer.json写"forwardPorts": [9229]，但没在docker-compose.yml加ports: ["9229:9229"]→ 断点永远连不上 - 以为
forwardPorts会自动开启 iptables 或修改容器网络策略 → 实际不会 - 混淆
forwardPorts和appPort（后者已弃用，勿用）
Python + debugpy 容器调试中断失败，重点查 debugpy.listen() 的 bind 地址和超时设置
debugpy 默认监听 127.0.0.1，且某些镜像（如 python:3.11-slim）缺少 psutil，会导致 attach 失败并静默超时。
实操建议：
- 启动脚本中显式调用
debugpy.listen(("0.0.0.0", 5678))，不要依赖--wait-for-client自动绑定 - 在容器内运行
python -c "import debugpy; debugpy.listen(('0.0.0.0', 5678))"测试是否能成功监听 - VSCode 的
launch.json中确保"host": "localhost"（指宿主机），"port": 5678，且"pathMappings"正确映射源码路径（例如"localRoot": "${workspaceFolder}","remoteRoot": "/workspace"） - 如果用
docker-compose，记得加extra_hosts: ["host.docker.internal:host-gateway"]，避免某些旧版 macOS/Windows 网络解析问题
调试容器中断的关键不在工具链多炫酷，而在三处对齐：容器内服务监听地址、Docker 端口映射规则、VSCode launch 配置中的 host/port/path。任一环节绑定到 127.0.0.1 或路径映射错一级，断点就彻底失效——这种问题往往看不出报错，只表现为“点了断点但没停”，最耗时间。
