断点变空心圆首要确认调试适配器是否真在容器内运行，而非仅装在宿主机；需进容器执行ps aux | grep debug验证，Python须显式安装debugpy，Node需--inspect=0.0.0.0:9229，Go编译需-gcflags="all=-N -l"，pathMappings必须字节级匹配，非root用户须统一UID并配置remoteUser，2026版推荐启用debug.enableContainerDebugging走Unix socket通信。
断点变空心圆？先确认调试适配器是否真在容器里跑
VSCode 显示断点但不命中，最常见原因是 debugpy、debugger-for-chrome 或 dlv 这类调试适配器没装进容器，而是只装在宿主机上。VSCode 本地前端只能和同侧（即容器内）的调试器通信。
检查方法：进容器执行 ps aux | grep debug 或 which debugpy；如果返回空，说明适配器缺失。
- Python 项目必须在
Dockerfile或devcontainer.json的features中显式安装debugpy，不能靠宿主机 pip 安装 - Node.js 项目需确保容器内 Node 版本 ≥18.17.0，且启动命令含
--inspect=0.0.0.0:9229 - Go 项目若用
dlv，要确认编译时加了-gcflags="all=-N -l"，否则符号被优化掉，断点会停在汇编层
pathMappings 配置错一个字符，断点就失效
pathMappings 不是“大概匹配”，而是调试器做源码校验的唯一依据。容器内路径和本地 ${workspaceFolder} 必须字节级一致，尤其注意开头斜杠、末尾是否带 /、大小写、WSL 路径中的 /mnt/c/ 前缀。
典型错误：
-
"remoteRoot": "/app"对应本地"localRoot": "${workspaceFolder}"—— 看似合理，但如果容器内实际工作目录是/workspace，断点必然失效 - 在 WSL 下开发，
remoteRoot写成C:\project（Windows 风格），而容器内路径是/workspace，完全不匹配 - 用了
docker-compose.yml的volumes挂载，但挂载目标路径和remoteRoot不一致，比如挂载到/src却设remoteRoot为/app
验证方式：在容器内运行 pwd 和 ls -l，把输出路径原样填进 remoteRoot。
非 root 用户权限断裂，导致调试器无法 attach 或读符号
新建文件属主是 root:root，但 git status 报 permission denied，这不是 Git 问题，是 UID 不匹配引发的调试链路断裂。VSCode 以用户身份启动容器进程，但调试器需要读取二进制、符号表、内存映射，权限不对就会静默失败。
必须统一 UID：
- 在
devcontainer.json中强制指定："remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 自定义
Dockerfile时，必须创建该用户并指定 UID（推荐和宿主机一致，如1001）：RUN useradd -m -u 1001 -G sudo vscode - 避免使用
USER root启动服务，否则调试器 attach 时因权限不足无法注入调试钩子
特别注意：某些基础镜像（如 python:3.11-slim）默认无 sudo，useradd 后需手动装 sudo 包，否则 vscode 用户无法执行调试所需系统调用。
VSCode 2026 新增的容器内调试代理，别手动开端口了
还在 docker run -p 5678:5678 手动暴露调试端口？VSCode 2026 的 debug.enableContainerDebugging 已改用 Unix domain socket（/run/vscode/debug.sock）通信，彻底绕过端口映射和防火墙问题。
启用条件很明确：
-
devcontainer.json中开启："debug.enableContainerDebugging": true - 确保 Remote-Containers 扩展是 v1.12+，且容器内已安装
common-utilsfeature - 删除所有旧式
portForwarding和EXPOSE相关配置，它们和新代理冲突
这个模式下，launch.json 可简化为纯声明式，甚至不用写 port 字段——VSCode 自动协商通信通道。但前提是容器内调试代理进程真实运行起来了，可通过 ps aux | grep vscode-debug-agent 验证。
最容易被忽略的是：新代理默认禁用 ptrace（出于安全），若调试 C++ 或需要深度内存分析，得在 runArgs 中显式加 --cap-add=SYS_PTRACE，否则 attach 会卡住或报 Operation not permitted。
