Golang环境搭建与依赖管理的关系解析_技术教程

Go 1.16+ 默认启用模块模式，GO111MODULE=on 强制依赖 go.mod/go.sum 管理，绕过 GOPATH；go mod tidy 才是同步依赖的权威命令，vendor 是可重现构建快照，go.sum 用于即时校验而非防篡改。

Go 1.16+ 默认启用 `GO111MODULE=on`，不手动设置也能走模块化

很多人卡在“为什么 go mod init 不生效”或“go get 还是往 $GOPATH/src 写”，本质是没意识到 Go 已经默认强制模块模式。从 Go 1.16 开始，只要项目根目录下有 go.mod（或能推导出 module path），所有依赖操作就绕过 GOPATH，直接管理到本地 go.mod 和 go.sum 中。

验证方式很简单：

go env GO111MODULE

输出一定是 on；即使你没设环境变量，它也生效。强行设成 off 反而容易触发 legacy 行为，比如把包下到 $GOPATH/src、无法解析相对路径导入等。

旧项目迁移：进项目根目录执行 go mod init example.com/myapp，立刻启用模块
新建项目：不用 cd $GOPATH/src，任意路径 mkdir myproj && cd myproj && go mod init myproj 即可
如果 go build 报错 “cannot find module providing package”，说明当前目录不在 module 根下，或 go.mod 缺失

`go mod tidy` 和 `go get` 的职责边界必须分清

go get 是“获取并记录依赖”，但它的行为受当前模块状态影响极大；go mod tidy 才是真正的“对齐声明与实际使用”。混淆二者会导致 go.sum 残留无用条目、间接依赖版本锁定错误、CI 构建不一致等问题。

go get -u 会升级直接依赖及其最新兼容的间接依赖，但不清理未被引用的包
go get some/pkg@v1.2.3 会写入 go.mod 并更新 go.sum，但不会自动删掉其他旧版本残留
go mod tidy 会扫描全部 .go 文件，只保留被 import 的包，删掉未使用的、补上缺失的、降级冲突的间接依赖
CI 中应优先跑 go mod tidy -e（-e 避免因编译失败中断），再 git diff --quiet go.mod go.sum || exit 1 确保声明干净

vendor 目录不是“备份”，而是构建确定性的快照

启用 go mod vendor 后，vendor/ 里不是简单复制一份源码，而是按 go.mod 锁定的精确版本 + go.sum 校验和生成的可重现副本。这意味着：

go build -mod=vendor 会完全忽略网络和 $GOPATH，只读 vendor/，适合离线构建或镜像打包
vendor/ 不随 go.mod 自动更新 —— 改了 go.mod 后必须重跑 go mod vendor，否则构建仍用旧 vendor
若项目用了 replace 指向本地路径（如 replace example.com/lib => ../lib），go mod vendor 默认不包含被 replace 的内容，需加 -v 参数才拉取
Git 提交 vendor/ 时，别漏掉 vendor/modules.txt —— 它是 vendor 内容的元描述，Go 1.14+ 依赖它做一致性校验

`go.sum` 文件里的校验和不是“防篡改保险”，而是模块加载时的即时验证依据

go.sum 每行形如 github.com/some/pkg v1.2.3 h1:abc123...，其中 h1: 是 Go 工具链计算的哈希，不是开发者手动生成的。它只在 go get、go mod download 或首次 go build 时写入或校验。

删掉 go.sum 再 go mod tidy，会重新生成 —— 但前提是所有依赖能从 proxy（如 proxy.golang.org）或源站下载成功
若某依赖在 go.sum 里有记录，但本地缓存损坏，go build 会报 “checksum mismatch”，此时不能手动改 go.sum，而该运行 go clean -modcache && go mod download
私有模块（如 GitLab 私仓）若没配 GOPROXY 或 replace，go.sum 可能写入不完整哈希（h1: 后为空或只有 go: 前缀），导致后续构建失败