devcontainer.json 中必须指定 image 或 Dockerfile 二者之一；推荐优先使用官方 devcontainers/go 镜像，它已预装 go、gopls、delve 等工具；若需自定义则用 Dockerfile，并注意路径、端口转发、GOPROXY 等配置。
devcontainer.json 里必须指定 image 还是 dockerfile？
二者选其一，不能同时存在，否则 VS Code 直接报错 Invalid devcontainer.json: Only one of 'image' or 'dockerfile' is allowed。用现成镜像（比如 mcr.microsoft.com/devcontainers/go:1.22）最省事；想自定义依赖或工具链，就写 Dockerfile 并在 devcontainer.json 中指向它。
常见错误是以为可以“先拉镜像再改配置”，结果 image 指向的镜像没装 git 或 gopls，导致后续调试失败。建议优先用官方 devcontainers/go 镜像，它已预装 go、gopls、delve 和基础构建工具。
-
image更快启动，适合标准 Go 开发场景 -
dockerfile可控性强，但每次修改都要 rebuild，CI/CD 中容易因缓存不一致出问题 - 本地开发时，
dockerfile路径必须相对于.devcontainer/或工作区根目录，写成./Dockerfile而不是绝对路径
Go module 路径和 workspaceFolder 不匹配会导致 go mod 报错
VS Code 启动容器后，workspaceFolder 默认挂载到容器内 /workspaces/<repo-name>。如果项目用了非标准 module path（比如 github.com/your-org/your-repo/sub/cmd），但 go.mod 文件不在挂载路径根目录，go 命令会找不到模块根，报 go: cannot find main module。
解决方法不是硬改 module path，而是确保 go.mod 在挂载路径下——也就是把代码 clone 到工作区根，别套太多子目录。如果必须嵌套，可在 devcontainer.json 中加：
立即学习“go语言免费学习笔记（深入）”；
"customizations": {
"vscode": {
"settings": {
"go.gopath": "/workspaces/your-repo",
"go.toolsEnvVars": {
"GOPATH": "/workspaces/your-repo"
}
}
}
}
- 不要手动在容器里
cd /workspaces/your-repo/sub/cmd && go run .，VS Code 的 Go 扩展依赖工作区根路径识别 module -
go.workplaceMode设为on可缓解部分路径识别问题，但治标不治本 - 使用
remote-ssh类比思路：容器内路径结构 = 本地工作区结构，别指望它自动“猜”module root
delve 调试失败：端口没暴露、dlv 启动参数不对
Dev Container 默认不暴露 dlv 的调试端口（通常是 2345），VS Code 就连不上。现象是点击「开始调试」后卡住，控制台只显示 Starting: dlv dap --continue-on-start=false...，没后续。
必须在 devcontainer.json 中显式声明端口转发：
"forwardPorts": [2345], "postCreateCommand": "go install github.com/go-delve/delve/cmd/dlv@latest"
还要注意 dlv 启动命令里的 --headless 和 --api-version=2 是必需的，VS Code 的 DAP 协议只认 v2。
-
postCreateCommand安装dlv时，别用go get（已弃用），用go install+ 版本号 - 如果项目含 cgo，容器里缺
gcc或musl-dev，dlv编译会静默失败，得进容器手动跑dlv version验证 - 调试远程服务（如 HTTP server）时，
dlv必须监听0.0.0.0:2345，不能只绑127.0.0.1，否则 VS Code 连不上
本地 GOOS/GOARCH 和容器不一致引发交叉编译问题
你在 macOS 上写代码，容器是 Linux amd64，但不小心在 main.go 里写了 //go:build darwin，运行时直接跳过——这不是 bug，是 Go 构建约束按容器 OS 生效。更隐蔽的是，GOOS=windows 本地构建二进制，放到容器里跑不了，因为容器没 Windows ABI。
Dev Container 的本质是“换了个 OS 环境编译运行”，所有构建行为都以容器为准。别依赖本地环境变量覆盖容器内行为。
-
GOOS和GOARCH应该由 CI/CD 或明确的make目标控制，不在devcontainer.json里设默认值 - 如果真要测试跨平台行为，用多阶段 Dockerfile，在构建阶段切
GOOS，运行阶段保持 Linux - VS Code 的 Go 扩展读取的是容器内的
go env，不是你本地终端的，检查时务必Ctrl+Shift+P → Dev Containers: Show Log
最常被忽略的一点：容器里 go env GOPROXY 默认是 https://proxy.golang.org,direct，国内网络下会超时卡死 go mod download。必须在 devcontainer.json 的 postCreateCommand 或 Dockerfile 里显式设 export GOPROXY=https://goproxy.cn，否则整个模块加载流程就停在那儿了。
