VSCode如何调试Docker容器内程序
调试容器内程序真正的难点，往往不在于建立连接本身，而在于路径、权限、符号、网络这四层嵌套映射是否全部严丝合缝地对齐。只要其中一环出错，VSCode通常只会沉默地显示“断点未绑定”，而不会告诉你具体是哪一环出了问题。
为什么 attach 到容器后断点不命中
当你顺利 attach 到容器，却发现断点怎么也打不中时，先别急着怀疑人生。最常见的原因无非两个：要么是容器内的程序本身缺少调试符号，要么就是 VSCode 的 launch.json 配置文件里，路径映射（sourceFileMap）没对上。
无论是 Go、Python 还是 Node.js，核心原则其实就两条：第一，容器里的程序必须能以某种方式被调试器接入；第二，你本地的代码路径必须和容器内程序“认为”的源码路径完全一致。举个例子，你的项目在本地是 /Users/me/project，但容器里的程序是从 /app 这个目录启动的，那么 sourceFileMap 就必须老老实实地写成 "/app": "${workspaceFolder}"。方向写反了，或者路径多了一层、少了一层，调试器就找不到源码，一切努力也就白费了。
- Go 程序：务必使用
dlv来启动（而不是直接用go run），并且记得加上必要的参数，例如--headless --api-version=2 --accept-multiclient --continue。 - Python 程序：需要在容器内安装
debugpy，并用类似python -m debugpy --listen 0.0.0.0:5678 --wait-for-client your_script.py的命令来启动。 - Node.js 程序：使用
node --inspect=0.0.0.0:9229启动，同时要确保容器内的这个端口已经正确暴露并映射到了宿主机。
如何配置 launch.json 让 attach 正确工作
指望 VSCode 官方的 Docker 扩展通过 type: "docker" 来自动完成所有配置，很多时候并不可靠。它的自动 attach 功能对于简单的标准镜像可能有效，但一旦遇到自定义构建或者非标准入口的容器，失败的概率就大大增加。
更稳妥的方式是手动配置 launch.json。将调试类型（type）明确设置为对应语言的调试器，比如 "cppdbg"、"pwa-node" 或 "go"，然后将请求类型（request）设为 "attach"，并正确填写 processId 或 port。
- 确认调试服务：首先，确保容器内确实有调试服务在运行。可以执行类似
docker exec -it myapp ps aux | grep debugpy的命令来验证。 - 端口映射：
launch.json中配置的port必须和容器内调试器监听的端口（例如 5678）完全一致，并且这个端口在启动容器时（docker run）已经通过-p 5678:5678参数暴露给了宿主机。 - 路径映射是关键：
sourceFileMap的配置至关重要。以 Python 项目为例，如果容器内工作目录是/app，那么映射通常写为"/app": "${workspaceFolder}"。这里最容易出错的就是路径层级，多写一层/src或少写一层，都会导致源码无法定位。 - Go 用户特别注意：
dlv默认只绑定在127.0.0.1上，这意味着容器外部无法访问。必须使用--listen=0.0.0.0:2345参数让它监听所有网络接口，VSCode 才能成功连接。
容器启动时没开调试端口怎么办
如果容器已经跑起来了，但启动时忘了开启调试端口，难道只能重新构建镜像吗？其实有个更快的临时补救办法：使用 docker commit 和 docker run。
docker commit -c 'EXPOSE 5678' -c 'CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "main.py"]' my-running-container temp-debug-img docker run -p 5678:5678 --rm temp-debug-img
当然，这只是应急措施。从长期维护的角度看，更建议在 Dockerfile 里做好规划。例如，采用分阶段构建，生产环境使用最精简的启动命令（CMD），而调试时则可以通过覆盖 ENTRYPOINT，或者设置环境变量（如 ENV DEBUG=1）来触发不同的启动逻辑。
- 关于 EXPOSE：需要明白，
Dockerfile中的EXPOSE指令更多是起文档说明作用，它本身并不会真正限制端口访问。安全控制应依赖于运行时的网络策略。 - 使用 Docker Compose：如果使用
docker-compose.yml，务必在服务配置的ports:部分写好端口映射。同时，注意避免为服务设置restart: unless-stopped这类策略，否则容器频繁重启可能导致调试连接不稳定。 - Windows/macOS 用户注意：Docker Desktop 底层使用的 WSL 2 或 Hyper-V 网络栈有时会出现问题，导致调试数据包丢失。如果遇到连接问题，可以尝试在 Docker Desktop 设置中暂时关闭 “Use the WSL 2 based engine” 选项，然后重试。
调试时变量显示为
调试过程中，发现变量值显示为
对于 C/C++/Rust 这类编译型语言，如果在构建容器镜像时使用了较高的优化等级（如 -O2），编译器可能会将局部变量优化到寄存器中，导致调试器无法访问其内存地址。同样地，Go 语言如果使用 go build -ldflags="-s -w" 进行构建，也会剥离调试符号信息。
- C/C++：在构建用于调试的镜像时，改用
gcc -g -O0这样的命令，牺牲一点镜像体积，换来完整的调试信息。 - Go：去掉构建命令中
-ldflags里的-s和-w参数，或者确保这些参数只在构建最终发布版本时才加上。 - 验证调试信息：可以通过命令验证容器内的二进制文件是否包含调试信息。执行
file /app/mybin，输出中应包含with debug_info字样；或者使用readelf -S /app/mybin | grep debug查看是否有调试段输出。 - 解释型语言：Python 和 Node.js 本身不受编译优化影响。但如果使用了 PyInstaller、pkg 等打包工具，它们会剥离运行时环境，自然也就失去了原生的调试能力。这种情况下，需要切回开发模式运行才能进行调试。
