使用Golang的go mod vendor解决内网构建失败 Go语言容器化打包

根本原因是go mod vendor默认只处理直接依赖，间接依赖和replace未同步导致内网构建失败；必须配合go build -mod=vendor使用，并确保vendor目录完整存在。

go mod vendor 为什么在内网构建时突然不生效

根本原因不是 go mod vendor 没运行，而是它默认只拉取 require 中的直接依赖，而内网构建失败往往卡在间接依赖（indirect）或 replace 后未同步的模块上。比如你用 github.com/gin-gonic/gin，它依赖的 golang.org/x/net 如果没进 vendor 目录，构建就会因无法访问外网失败。

• 执行前先确认 GOPROXY 是否被清空或设为 direct：检查 go env GOPROXY，内网必须设为 off 或指向私有代理（如 https://goproxy.example.com）
• go mod vendor 必须在模块根目录（含 go.mod 的目录）下运行，否则生成的 vendor/ 不完整
• 如果 go.mod 里有 replace，比如 replace golang.org/x/crypto => ./vendor_golang_org_x_crypto，vendor 不会自动处理这种本地路径替换——得先删掉 replace，跑完 go mod vendor 再手动补回（或改用 go mod edit -replace 指向 vendor 内路径）

容器化打包时 vendor 目录被忽略的常见配置坑

docker 构建阶段常因 .dockerignore 或 copy 范围错误导致 vendor/ 没进镜像。最典型的是 .dockerignore 里写了 **/* 却漏掉了 !vendor，或者 COPY 只写了 COPY . . 却没确认当前上下文是否真包含 vendor 目录。

• 运行 docker build -f Dockerfile . 前，先 ls vendor 确认目录存在且非空；再 cat .dockerignore 检查有没有意外屏蔽 vendor/
• Dockerfile 中推荐显式 COPY：COPY go.mod go.sum ./ → RUN go mod download → COPY vendor ./vendor → COPY . .，避免把本地未 commit 的临时文件带入
• 使用 go build -mod=vendor 编译，而不是依赖 GOPATH 或默认 -mod=readonly；否则即使 vendor 存在，Go 仍会尝试联网校验

go mod vendor 和 go build -mod=vendor 的行为差异

go mod vendor 是一次性的依赖快照操作，生成静态文件；而 go build -mod=vendor 是编译时的行为开关——它强制 Go 工具链只读 vendor/ 下代码，完全跳过 module cache 和网络请求。两者必须配合，缺一不可。

• 如果只运行 go mod vendor 但编译时不加 -mod=vendor，Go 仍可能去 $GOMODCACHE 查间接依赖，导致内网失败
• go build -mod=vendor 会严格校验 vendor/modules.txt 和实际文件一致性；若有人手动删了 vendor 里的某个子目录但没更新 modules.txt，构建会报错：vendor/modules.txt is out of date
• CI/CD 流水线中建议加一步验证：go mod vendor && git status --porcelain vendor/ | grep -q '.' && echo "vendor changed" && exit 1 || true，防止 vendor 状态漂移

交叉编译 + vendor 场景下 CGO_ENABLED 的陷阱

容器内构建常需交叉编译（如 linux AMD64 镜像里编译 ARM64 二进制），此时若项目含 C 依赖（如 sqlite、openssl），CGO_ENABLED=0 会让编译跳过 vendor 中的 C 文件，但 CGO_ENABLED=1 又可能因缺失交叉工具链而失败。

立即学习“go语言免费学习笔记（深入）”；

• 纯 Go 项目（无 cgo）可安全设 CGO_ENABLED=0，这时 go build -mod=vendor 完全离线，vendor 里所有 .go 文件都有效
• 含 cgo 的项目，CGO_ENABLED=1 时 vendor 中的 *.c / *.h 文件会被读取，但系统级头文件（如 stdlib.h）仍需宿主机提供——内网构建机必须预装对应平台的 gcc-arm64-linux-gnu 等交叉工具链
• 验证方式：在构建容器里运行 go list -f '{{.CgoFiles}}' ./...，看输出是否为空；非空则必须处理 cgo 依赖链，不能只靠 vendor

事情说清了就结束。最关键的其实是两件事：vendor 目录必须真实存在且完整，以及每次构建命令都得明确带上 -mod=vendor——少一个，内网就断连。