go build报checksum mismatch本质是下载包内容与go.sum记录哈希不一致，需删go.sum后运行go mod tidy重建；第三方工具如swag会隐式触发go list连网，离线时须设GOPROXY=off、预装二进制并配GOPRIVATE。
Go 编译时依赖拉取失败，90% 不是代码问题，而是网络、缓存或工具链行为没对齐。 直接看 go.mod 和 go.sum 状态、第三方工具是否偷偷连网、私有模块是否被正确识别，比反复重试 go get 更快定位根因。
go build 报 checksum mismatch 怎么办
这是最典型的构建中断现象，本质是本地下载的包内容和 go.sum 中记录的哈希值对不上。不是网络污染，而是校验文件状态不一致。
-
go.sum被手动删减或编辑过 —— 它必须由go mod tidy自动生成并提交，禁止手改 - 执行过
go mod download后又提交了新生成的go.sum—— 这会让其他协作者本地校验失败，因为go.sum应该只在开发者运行go mod tidy后提交 - CI 中设了
GOSUMDB=off或跳过go.sum校验 —— 失去防篡改能力，且破坏可重现性 - 私有模块未配置
GOINSECURE或 git credential，导致代理 fallback 到不一致源
修复建议：先 rm -f go.sum，再运行 go mod tidy 重建；若仍报错，加 -x 参数看实际下载 URL，确认是否命中了非预期镜像或 fork。
第三方工具（如 swag、mockgen）在离线环境卡住
go build 本身不偷偷连网，真正触发隐式下载的是第三方工具在运行时调用 go list -m all 或 go mod download。它们没加 -mod=readonly 或没设 GOPROXY=off，一执行就直连 proxy.golang.org 导致超时失败。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 所有这类工具必须在离线机上提前安装好二进制（别用
go install动态拉），且版本与联网机一致 - 运行前统一设置环境变量：
go env -w GOPROXY=off GOSUMDB=off，否则工具内部的go命令仍会尝试校验 - 若工具依赖特定模块（如
swag需要github.com/swaggo/swag@latest），得在联网机用对应版本运行一次该工具，让其触发的模块也进缓存 - 检查工具文档，确认是否支持
-mod=readonly参数（部分新版swag支持swag init -mod=readonly）
replace 私有模块后，go list 或工具仍解析失败
replace 写在 go.mod 里，只影响当前 module 的构建上下文；但第三方工具（尤其是基于 go/packages 的）往往启动独立的 go list 进程，不继承你的 replace 规则，导致它仍试图解析原始 URL（如 gitlab.internal/foo/bar），而离线机 DNS 不通或 Git 服务不可达。
- 不要只靠
replace，对私有模块，必须同时用go mod edit -replace=gitlab.internal/foo/bar=./internal/foo/bar指向本地路径，并确保该路径真实存在且含完整go.mod - 把私有模块目录一起打包进项目（如
./internal/foo/bar），而非仅靠replace指向远程地址 - 若工具强制走
go list，可在其调用前临时设GOPRIVATE=gitlab.internal，避免代理转发 - 验证：在离线机运行
go list -m gitlab.internal/foo/bar，应直接返回本地路径，而不是报错或超时
vendor 目录存在，但 go build -mod=vendor 仍失败
go mod vendor 只是复制依赖到本地，并不改变 Go 工具链默认行为。从 Go 1.14 起，即使有 vendor/，go build 仍会走 GOPROXY 校验或补全缺失间接依赖。
- 构建时必须显式加
-mod=vendor参数：go build -mod=vendor - 每次修改依赖后，要重新运行
go mod vendor并git add提交，否则vendor/内容与go.mod不同步 - 某些工具（如
swag）内部仍会调用go list -m all，此时需配合GOPROXY=off和GOPRIVATE才能完全离线 -
vendor/不解决go.sum校验问题 —— 若go.sum与 vendor 内容不匹配，go build -mod=vendor仍会失败
最容易被忽略的一点是：很多失败根本不是 go build 自己的问题，而是你调用的工具（比如 swag init、mockgen、stringer）在后台悄悄执行了 go list 或 go mod download。不查清具体哪个命令触发了网络请求，只改 go build 参数永远治标不治本。
