直接用golang:1.22-bookworm镜像+docker-compose.yml编排可实现开箱即用的本地开发闭环，因其自带go/dlv/gofmt、支持cgo且体积可控；而golang:latest易引发版本漂移兼容问题，自建Dockerfile则破坏快速反馈流程。
直接用 golang:1.22-bookworm 镜像 + docker-compose.yml 编排，配合 reflex 热重载和 -mod=vendor 模式，能跑通本地开发闭环——不编译镜像、不改宿主机环境、不依赖 GOPATH，80% 的 Go 项目开箱即用。
为什么别碰 golang:latest 和自建 Dockerfile
用 golang:latest 会悄悄升级到 1.23+，而很多 CI 脚本、Delve 版本、第三方库还没适配；自己写 Dockerfile 构建镜像，等于把本地开发变成“构建-推送-拉取-运行”流程，失去快速反馈意义。官方 golang:1.22-bookworm 镜像自带 go、dlv、gofmt，体积可控（约 900MB），且支持 cgo（比如 pgx、sqlite3 驱动）。
常见错误现象：go run main.go 报 no Go files in current directory，本质是 WORKDIR 没设对，或挂载路径错位；更隐蔽的是 go mod download 卡住，其实是容器内没配 GOPROXY。
- 必须显式设置
working_dir: /app，否则go run默认在/下找文件 - 所有挂载路径用绝对路径：如
./:/app，不能写成./src:/app再靠COPY—— 开发阶段不需要 COPY - 在
environment中加GOPROXY: https://goproxy.cn,direct，避免首次go run卡死
热重载必须用 reflex，不是 nodemon
nodemon 是 Node.js 工具，启动时会尝试加载 node_modules，进 Go 容器里直接报 command not found；reflex 是纯 Go 实现的监听器，轻量、无依赖、正则匹配精准。它唯一要求是 Alpine 镜像里用 apk add --no-cache reflex 安装（Debian/Bookworm 镜像用 apt-get install -y reflex）。
立即学习“go语言免费学习笔记（深入）”；
容易踩的坑：command: reflex -r "\.go$" -- go run main.go 这条命令里，"\.go$" 的双引号不能丢，否则 shell 在 compose 解析阶段就展开成空字符串，导致 reflex 监听失败；另一个常见问题是 reflex 启动后没输出，其实是它默认静默，加 -v 参数可看日志。
- 推荐命令写法：
reflex -v -r "\.go$" -- sh -c "go run -mod=vendor main.go" - 若项目没
vendor/，先在宿主机执行go mod vendor，再挂载：./vendor:/app/vendor:ro - 别在
command里写sleep infinity+ 另起终端go run——这破坏了热重载前提
调试端口暴露和 Delve 启动参数要配对
VS Code 连不上容器里的 Delve，90% 是因为 dlv 启动时绑定了 127.0.0.1:2345，而容器内 127.0.0.1 不等于宿主机；必须改成 0.0.0.0:2345，且 docker-compose.yml 中得对应暴露该端口。
性能影响：Delve 默认开启源码映射和符号表加载，对大项目启动慢；但开发阶段不能关，否则断点失效。折中方案是加 --headless --api-version=2 --accept-multiclient，不启 Web UI，只留调试协议。
-
ports必须写：- "2345:2345"，不能只写2345 -
command改为：dlv debug --headless --api-version=2 --addr=0.0.0.0:2345 --accept-multiclient --continue --log --log-output=debugger - VS Code 的
launch.json中port填2345，host填localhost（走宿主机端口映射）
本地编译加速靠三件事：缓存、代理、禁 CGO
真正拖慢 go run 的往往不是编译本身，而是模块下载和缓存未命中。宿主机上配置好 GOCACHE 和 GOMODCACHE 对容器内无效，因为容器是隔离环境；但你可以把宿主机的缓存目录挂进容器，复用已有成果。
容易被忽略的点：CGO_ENABLED=0 能跳过 C 依赖解析，让 go build 快 30%+，但前提是你的项目真不用 cgo（比如没连 PostgreSQL、没调用图像处理库）。试错方法很简单：临时加 environment: CGO_ENABLED: "0"，如果 go run 报 undefined reference to ...，那就得关掉。
- 宿主机执行：
go env -w GOCACHE=$HOME/.cache/go-build，然后在volumes中挂载：$HOME/.cache/go-build:/root/.cache/go-build -
GOPROXY必须设，国内用https://goproxy.cn,direct；别信direct会自动 fallback——它不会，只会卡住 - 测试阶段加
-race或-gcflags="all=-N -l"会显著变慢，仅在需要时启用
最麻烦的永远不是配置项本身，而是不同 Go 版本间 dlv 的 API 兼容性、go mod vendor 生成的 checksum 差异、以及 reflex 在不同 shell 下对引号的解析行为——这些细节不出错时没人注意，一出就是“明明文档写了却跑不通”。建议第一次搭环境时，把 docker-compose.yml 和 go.mod 提交到仓库，锁定版本组合。
