断点失效主因是路径映射错误、inspector未启用或权限缺失：需正确配置--inspect=0.0.0.0:9229、-p 9229:9229、launch.json中localroot与remoteroot严格匹配挂载路径，且容器需预装调试依赖并开放sys_ptrace权限。

能直接在容器里打断点，但必须让调试器“看见”源码路径和运行时状态，否则断点永远是灰的。

node --inspect=0.0.0.0:9229 启动失败或断点不生效

常见现象是 VS Code 显示 “Breakpoint ignored because generated code not found”，或者调试器连上后立刻断开。根本原因不是端口没映射，而是 Node.js 进程没真正启用 V8 inspector 协议，或监听地址不对。

• --inspect 必须加在 node 命令之后、脚本路径之前，顺序错（比如写成 node server.js --inspect）就无效
• 容器内监听必须用 --inspect=0.0.0.0:9229，不能只写 --inspect（默认只绑 127.0.0.1）
• 如果镜像基于 node:alpine，某些精简版可能默认不带 inspector 模块，需改用 node:18-slim 或更高版本
• Docker 启动时要加 -p 9229:9229，且确保宿主机防火墙没拦截该端口

VS Code launch.json 中 localRoot / remoteRoot 配置错误

这是断点变灰最常被忽略的一环：VS Code 不知道容器里的 /app/server.js 对应本地哪个文件。它靠路径映射匹配，而不是文件名或内容哈希。

Docker Cli

使用 Docker CLI 构建、运行、停止、检查和管理容器与镜像的助手。用于执行容器相关任务。

下载

• localRoot 必须是当前工作区的绝对路径（推荐用 ${workspaceFolder}）
• remoteRoot 必须和 -v 挂载时容器内的路径完全一致，比如 docker run -v $(pwd):/app → remoteRoot 就得是 /app，少一个斜杠都不行
• Windows 用户注意路径分隔符：localRoot 用 \ 或正斜杠都行，但 remoteRoot 在 Linux 容器里只能是 /app，不能写成 C:\project
• 如果用了 Docker Compose，挂载路径以 volumes: 字段为准，不是 working_dir

ROS/C++/Go 等非 Node.js 项目需要额外注入调试器

Node.js 有内置 inspector，C++ 和 Go 则依赖外部调试器（gdb / dlv），它们不通过 HTTP 端口通信，而是走进程级 attach，因此容器必须满足更严苛条件。

• C++ 调试需在容器内安装 gdb，且编译时加 -g（add_definitions("-g") 或 CMake -DCMAKE_BUILD_TYPE=Debug）
• Go 项目要用 dlv 启动：dlv debug --headless --listen=:2345 --api-version=2 --accept-multiclient，再映射 -p 2345:2345
• ROS 场景下，remoteRoot 得指向 devel/lib/xxx 下的真实可执行文件路径，不是 launch 文件
• 所有语言都要求容器启动时加 --cap-add=SYS_PTRACE，否则 gdb/dlv attach 会 Permission denied

Dev Container 方式比手动 attach 更稳定但有隐藏约束

VS Code 2026 的 Dev Container 模式省去了手写 launch.json，但它的稳定性建立在几个硬性前提上，漏掉任一环节都会回退到传统 attach 模式甚至失败。

• .devcontainer/devcontainer.json 中的 workspaceFolder 必须和 docker run -v 实际挂载路径一致，否则编辑器打开的是空目录
• 多容器场景（如 db + app）中，只有 service 字段指定的那个服务会被自动注入调试桩，其他容器不会响应断点
• 如果基础镜像没预装 openssh-server（比如 Alpine 默认不带），Dev Container 会静默 fallback 到 exec 模式，导致无法热重载或变量监视失效
• features 里声明的 ms-vscode.container-debug 版本必须与 VS Code 内核匹配，2026.1.0 不兼容 2025.x 版本

真正卡住人的往往不是“怎么配”，而是“为什么配了还不行”——绝大多数问题出在路径映射偏差、权限缺失或调试器未就绪这三点上。动手前先 docker exec -it ps aux | grep -E "(node|gdb|dlv)" 确认进程真在跑，比反复改配置高效得多。