VS Code 调试容器内程序时断点不生效怎么办

VS Code 在容器里调试时，断点不生效通常不是“断点坏了”，而是编辑器窗口、调试进程和源码路径没有处在同一个上下文。先确认左下角已经进入 Dev Container，再检查 launch.json 选择的调试适配器，最后把 localRoot、remoteRoot 或 source map 对齐。下面用 Node.js 容器作为例子，重点看每一步屏幕上应该出现什么。

官方地址：https://code.visualstudio.com/docs/containers/debug-common

先确认 VS Code 真的在容器上下文

先不要急着改配置。按 View → Command Palette，执行 Dev Containers: Reopen in Container，等待窗口重新加载。左下角应该出现远程容器标识；再打开 Terminal → New Terminal，确认终端标题或提示符显示在 Container 上下文中。

可以用两个无副作用的命令确认当前终端看到的工作目录。这里的输出只是检查入口，不代表程序已经开始调试：

# 确认终端当前看到的是容器内工作目录
pwd

# 确认 Node.js 进程使用的当前目录
node -p "process.cwd()"

如果编辑器打开的是宿主机项目，而终端却进入了容器，或者两处工作目录不一致，断点可能会落在另一份文件上。先统一上下文，再进入下一步。

让调试适配器和 launch.json 指向同一个目标

打开左侧 Run and Debug，点击创建或打开 .vscode/launch.json。本例假设 Node.js 进程在容器内以调试端口 9229 运行，使用“附加”方式连接。下面是最小配置，JSON 本身不写注释；每个字段的用途放在代码块外解释。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Node in Container",
      "type": "node",
      "request": "attach",
      "address": "127.0.0.1",
      "port": 9229,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/workspace/app",
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

type 决定调试适配器，request 决定是启动还是附加；本例的 attach 必须对应一个已经开放调试端口的 Node.js 进程。如果你使用 Container Tools 自动生成配置，还要确认 Dockerfile、docker-build 和 docker-run 任务都属于当前项目，而不是另一个窗口。

改完后，在 Run and Debug 顶部配置下拉框选择 Attach to Node in Container。如果下拉框没有它，先保存 launch.json，再检查 JSON 括号、调试扩展是否安装在当前远程窗口，以及当前窗口是否真的连接到容器。

断点空心时，优先检查路径映射和转译文件

容器内的真实文件可能是 /workspace/app/src/server.ts，而调试器报告的是构建后的 /workspace/app/dist/server.js。此时编辑器知道你点了一个断点，却找不到运行时对应的源码位置，就会出现空心断点或停在不可编辑的生成文件上。

检查三件事：

1. remoteRoot 必须等于 Node.js 进程看到的项目根目录；不要凭宿主机路径猜测，应该以容器内工作目录为准。
2. localRoot 要对应 VS Code 当前工作区；使用 Dev Container 窗口时，通常应从当前工作区变量开始，而不是硬编码另一台机器的路径。
3. 如果 TypeScript、Babel 或 bundler 生成了 dist，让 outFiles 指向实际生成的 JavaScript，且构建产物带有可用 source map。

现在回到编辑器，在真正会被请求触发的源码行左侧点击一次断点，然后按 F5。用一个最小请求触发该行。成功信号不是“F5 没报错”，而是编辑器出现黄色执行箭头，并且 Call Stack 的文件路径能回到当前编辑器文件，Variables 面板能看到本次暂停时的变量值。

按症状快速定位，不要同时改多个变量

常见问题

只装了 Docker 扩展，为什么还是不能附加调试？

扩展负责提供任务或配置入口，真正暂停程序还需要对应语言的调试适配器和一个可连接的调试进程。先在当前容器窗口确认扩展状态，再确认端口映射和进程启动参数。

断点变红了但仍然不停，说明路径已经正确吗？

不一定。红点只表示编辑器保存了断点；只有命中后出现黄色执行箭头、调用栈和变量，才说明运行时文件、路径映射与触发请求都对上了。

什么时候该用 Rebuild and Reopen？

如果改动的是 devcontainer.json、Dockerfile 或 Compose 配置，需要重建让配置进入新容器；如果只是修改 launch.json，通常保存后重新选择配置即可，不必每次重建。

最后按“远程标识 → 调试配置 → 端口 → 路径 → 命中状态”的顺序复查。只要 Call Stack 能回到当前文件，Variables 能显示暂停时值，容器内断点链路就已经建立。