离线构建必须用 go mod vendor + -mod=vendor：go mod vendor 将 go.mod 中所有依赖（含间接依赖）复制到 ./vendor 目录，但仅生成目录不够，必须显式加 -mod=vendor 参数才能禁用网络查找，否则仍会尝试访问 $gopath/pkg/mod 或 goproxy。

离线构建必须用 go mod vendor + -mod=vendor

没有网络时，go build 会直接失败，除非你提前把所有依赖“打包进项目”。go mod vendor 就是干这事的：它把 go.mod 里声明的所有依赖（含间接依赖）复制到 ./vendor 目录，生成可提交的代码快照。

但光有 vendor/ 目录不够——Go 默认仍会尝试读 $GOPATH/pkg/mod 或走 GOPROXY。必须显式加 -mod=vendor 参数，否则构建行为和没 vendor 一样。

• CI/CD 流水线跑在内网机器上？必须加 GOFLAGS="-mod=vendor" 或每条命令都带参数
• 临时断网调试？删掉 $GOPATH/pkg/mod/cache 后再试 go build -mod=vendor，失败就说明没生效
• go test -mod=vendor 和 go run -mod=vendor 同样要加，不能只给 build 加

go mod vendor 不等于“全量复制”，缺包常见于这几种情况

go mod vendor 只复制当前构建上下文实际用到的包，不是 go.mod 里写了就一定进 vendor/。典型漏包场景：

• _test.go 里 import 的包，如果没被主代码引用，go build 时不参与编译，go mod vendor 就不会复制它
• 用了 //go:embed 或 //go:generate 但没显式 import，工具链无法静态分析，该包会被跳过
• go.mod 中有 replace 指向本地路径（如 replace example.com/a => ../common），默认不复制；需加 -v 参数才尝试包含
• 私有仓库依赖没设 GOPRIVATE，go mod vendor 会卡住或静默失败，不是报错而是缺包

验证是否全量：运行 go list -f '{{.Dir}}' all | grep '^vendor/' | wc -l，和 go list all | wc -l 对比，数字不一致就是漏了。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

-mod=vendor 会忽略 replace，这点必须手动绕过

一旦加了 -mod=vendor，Go 工具链就完全跳过 go.mod 里的 replace 指令——包括指向本地目录的替换。这意味着：

• 如果你靠 replace github.com/foo => ./local-foo 开发调试，go build -mod=vendor 会报错：找不到 github.com/foo
• go mod vendor 本身也不复制 ./local-foo，它只处理远程模块
• 解决方案只有两个：要么去掉 replace、改用真实版本；要么构建时不加 -mod=vendor，改用 go build + 确保 GOPROXY=off + GOPRIVATE 配置完整

这不是 bug，是设计使然：vendor 模式追求的是“确定性快照”，而 replace 是动态开发手段，二者逻辑冲突。

要不要把 vendor/ 提交进 Git？看你的交付粒度

vendor/ 目录体积大（动辄几十 MB），频繁提交会拖慢 clone 和 diff。但它是否该进 Git，取决于你对“构建可重现”的定义：

• 需要保证任意人、任意时间、任意机器上 git clone && go build -mod=vendor 就能成功？那就提交 vendor/，但记得 .gitignore 排除 vendor/modules.txt（它由 Go 自动生成，不该手改）
• 只是为 CI 提供离线能力，且你信任 go mod download + 缓存归档？那就不提交 vendor/，CI 脚本里先 go mod download 再 go mod vendor，构建阶段用 -mod=vendor
• 安全审计或长期归档场景？vendor/ 本身不带哈希校验，必须配合 go.sum 使用；单靠 vendor/ 无法防篡改

最常被忽略的一点：vendor/modules.txt 第一行必须和 go.mod 中 require 的版本严格一致，否则 -mod=vendor 构建时可能触发网络请求去补 go.sum 条目，导致超时或失败。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！