Docker构建Golang环境教程

最稳妥的Go开发环境是使用官方golang:1.22镜像并挂载本地目录：docker run -it --rm -v $(pwd):/workspace -w /workspace golang:1.22，配合GOPATH缓存和Delve正确参数实现高效调试。

用官方 golang 镜像做开发环境最稳妥

直接拉取 golang:1.22（或最新稳定版）镜像，它自带 go、git、gcc（用于 cgo）、vim 和基础构建工具，省去手动装依赖的麻烦。别用 alpine 版本做开发环境——虽然镜像小，但缺少调试工具（如 delve 依赖的 libc 符号）、gdb 不兼容、交叉编译链也不全，改个断点都可能卡住。

常见错误：有人把 Dockerfile 写成只 COPY . /app 然后 go run main.go，结果每次改代码都要重构建镜像——这根本不是开发环境，是运行时封装。

docker run -it --rm -v $(pwd):/workspace -w /workspace golang:1.22 是核心命令

这条命令才是本地开发流的核心：挂载当前目录到容器内 /workspace，工作目录也设为它，进容器就能直接 go build 或 go test。关键点：

• -v $(pwd):/workspace 必须用绝对路径，Mac/Linux 可用 $(pwd)，Windows WSL 下建议用 /mnt/c/Users/xxx/project 格式
• -w /workspace 不加的话默认在 /root，go mod init 会建错路径
• 加 --rm 避免退出后留一堆停止态容器；需要后台调试可换 -d + docker exec -it
• 如果项目用了 CGO_ENABLED=1，记得加 -e CGO_ENABLED=1，否则 sqlite/pq 等包编译失败

Go modules 依赖缓存不能靠 COPY go.mod/go.sum 解决

开发阶段频繁 go mod download 很慢，又不想每次重拉整个 pkg 目录。正确做法是复用宿主机的 $GOPATH/pkg/mod：

先查宿主机 GOPATH：go env GOPATH，假设输出 /home/user/go，则启动容器时加：
-v /home/user/go/pkg/mod:/go/pkg/mod

注意：/go 是镜像内默认 GOPATH，必须映射到这个路径才生效；映射 /go 整体也可以，但会覆盖镜像里预置的 bin 工具，不推荐。

如果团队共用一套依赖，还可把 /go/pkg/mod 挂到命名卷：docker volume create go-mod-cache，再用 -v go-mod-cache:/go/pkg/mod，避免路径硬编码。

调试时 dlv 启动参数容易漏掉 --headless --api-version=2

想在容器里用 VS Code 连 Delve，光装 dlv 不够。必须用以下方式启动：

dlv debug --headless --api-version=2 --addr=:2345 --continue

缺 --headless 会卡在交互模式；--api-version=2 是 VS Code Go 插件强制要求的版本，v1 已废弃；--addr=:2345 的冒号前不能有空格，否则绑定失败，日志里只报 could not launch process: stub exited while waiting for connection，很难排查。

顺带一提：VS Code 的 launch.json 里 "port": 2345 对应容器端口，若用 docker run -p 2345:2345 暴露，就不用改配置；但如果容器跑在远程服务器，注意防火墙和 dlv 的 --accept-multiclient 参数是否开启。

复杂点在于：Delve 调试时读的是容器内路径，而 VS Code 打开的是宿主机文件。只要代码挂载路径一致（比如都用 /workspace），断点才能命中。路径对不上，断点全是空心圆。