go mod init 必须在项目根目录执行，因模块路径基于当前路径推导，若不在根目录会导致 go.mod 中模块名与 import 路径不一致，引发“cannot find module providing package”错误；正确做法是 cd 至含 main.go 的根目录后执行 go mod init example.com/myapp。
go mod init 必须在项目根目录执行
很多人在任意子目录下运行 go mod init，结果生成的模块路径和实际 import 路径不一致，导致后续 go build 或 go test 报错：「cannot find module providing package」。模块路径必须与代码中 import 的路径完全匹配，否则 Go 工具链无法解析依赖。
正确做法是：确保当前工作目录就是项目根目录（即包含 main.go 或 go.mod 应该所在的位置），再执行：
go mod init example.com/myapp
这个 example.com/myapp 就是模块名，后续所有包导入都以此为前缀，比如 example.com/myapp/internal/handler。
GOVERSION 和 go.mod 中的 go 版本要对齐
Go 1.17+ 强制要求 go.mod 文件首行声明 go 1.21 这类版本号。如果本地 GOVERSION 是 1.21，但 go.mod 写的是 go 1.19，某些新语法（如泛型约束、any 类型别名）会被拒绝编译；反过来，若 go.mod 声明了 1.21，但 CI 环境只有 1.20，则 go build 直接失败。
立即学习“go语言免费学习笔记（深入）”；
建议统一方式：
- 用
go version查看本地 Go 版本，然后手动写入go.mod - 或直接用
go mod edit -go=1.21更新（避免手误） - CI 配置中显式指定 Go 版本，例如 GitHub Actions 的
actions/setup-go@v4中设置go-version: '1.21'
go.sum 不应被忽略或手动修改
go.sum 是 Go 模块校验和文件，记录每个依赖模块的哈希值。它不是“可选附件”，而是构建可重复性的关键凭证。常见错误包括：
- Git 提交时忽略
go.sum→ 下次拉取后go build可能因 checksum mismatch 失败 - 手动删掉某行以绕过校验 → 后续
go get会重新生成，且可能引入不一致版本 - 多人协作中某人用了代理或私有镜像源，导致
go.sum写入了不同域名的 hash → 其他人拉取后校验失败
正确做法：始终提交 go.sum，并确保团队使用相同 GOPROXY（推荐 https://proxy.golang.org,direct）。若需切换镜像源，用 go env -w GOPROXY=...，而不是临时改环境变量再 go mod download。
Docker 构建时别依赖宿主机的 $GOPATH
在容器里复用宿主机的 GOPATH 或 GOROOT 是典型陷阱。Docker 镜像内 Go 环境是独立的，$GOPATH 默认是 /go，而宿主机可能是 ~/go。如果 Dockerfile 里写 COPY ~/go/pkg/mod /go/pkg/mod，构建必然失败 —— 容器里根本没有 ~/go。
安全做法是让容器自己下载依赖：
FROM golang:1.21-alpine<br>WORKDIR /app<br>COPY go.mod go.sum ./<br>RUN go mod download<br>COPY . .<br>RUN go build -o myapp .
注意两步分离：COPY go.mod + go.sum → go mod download → COPY 其余代码。这样能利用 Docker 层缓存，只要依赖没变，就不重跑 download 步骤。
真正容易被忽略的点是：可重复性 ≠ “能跑起来”，而是“在任何节点上，给定同一份代码和同一份 go.mod/go.sum，输出的二进制行为完全一致”。这意味着你得同时控制 Go 版本、模块校验、构建命令参数（比如是否加 -ldflags）、甚至 CGO_ENABLED 设置 —— 它们全都会影响最终产物。
