根本原因是调试器进程未在容器内正确启动或VSCode未获取调试协议入口；"forwardPorts"仅映射端口，不启动服务；须确保调试器监听0.0.0.0、配置pathMappings、区分Dockerfile与devcontainer.json职责。
为什么 devcontainer.json 里配了端口却连不上调试器
常见现象是 VSCode 显示 “Attaching to container…” 后卡住，或调试器断点完全不触发。根本原因不是端口没开，而是调试器进程没在容器内正确启动，或者 VSCode 没拿到调试协议入口。
-
devcontainer.json中的"forwardPorts"只做端口映射，不等于启动调试服务——它只是把容器内某个端口暴露给宿主机，但容器里得真有进程在监听那个端口 - Python 用户容易漏掉
"python.defaultInterpreterPath"或没在postCreateCommand里装debugpy；Node.js 用户常忘了加--inspect=0.0.0.0:9229启动参数 - 如果容器用的是非 root 用户（推荐），但调试器绑定在
127.0.0.1，会导致 VSCode 宿主机无法反向连接——必须用0.0.0.0
示例（Python）：
"postCreateCommand": "pip install debugpy",<br>"customizations": {<br> "vscode": {<br> "settings": {<br> "python.defaultInterpreterPath": "/usr/local/bin/python",<br> "python.debugging.port": 5678<br> }<br> }<br>}
调试 Node.js 时 attach 模式总报 Connection refused
这是 Remote-Containers 下最典型的网络错位：VSCode 尝试连容器内的 127.0.0.1:9229，但该地址在容器网络命名空间里指向容器自身，而调试器实际可能只监听了 localhost（即仅限 loopback）。
- 启动命令必须显式指定
--inspect=0.0.0.0:9229，不能只写--inspect（默认绑127.0.0.1） -
devcontainer.json的"forwardPorts"要包含9229，否则宿主机根本收不到包 - 某些基础镜像（如
node:alpine）缺少ps或netstat，导致 VSCode 内置的端口探测失败——可临时加"waitForDebugger": true避免超时退出
devcontainer.json 和 Dockerfile 的职责边界在哪
很多人把所有环境配置塞进 Dockerfile，结果每次改个 Python 包都要 rebuild 镜像；也有人全扔 devcontainer.json，导致容器启动慢、不可复现。
-
Dockerfile负责固化运行时依赖：系统工具（curl、git）、语言运行时（python3.11、node18）、全局 CLI（pipx、nvm） -
devcontainer.json负责开发期配置：VSCode 插件、端口转发、初始化脚本（postCreateCommand）、挂载路径（mounts）、非 root 用户权限适配 - 避免在
postCreateCommand里执行耗时操作（如npm install），应提前写进Dockerfile；但项目级依赖（requirements.txt）可保留在postCreateCommand，方便热更新
容器内调试时断点不命中，但日志显示已 attach
表面成功，实则调试器和代码不在同一上下文。尤其多工作区、符号路径错位、或使用了打包工具（Webpack、Vite）时高频发生。
- 确认源码映射：VSCode 默认假设容器内路径与本地一致；若用了
workspaceMount或自定义挂载，需在launch.json里配"pathMappings"，例如"/workspaces/myapp": "${workspaceFolder}" - TypeScript 项目务必检查
tsconfig.json是否启用了"sourceMap": true和"inlineSourceMap": false（后者会让 map 嵌入 JS，Remote-Containers 有时解析失败） - 使用
docker exec -it手动确认调试进程是否真在运行、监听地址是否为ps aux 0.0.0.0而非127.0.0.1
复杂点永远在路径映射和监听地址上——哪怕其他都对，只要 pathMappings 少一个斜杠，或 --inspect 漏了 =0.0.0.0，断点就静默失效。
