CI 禁用 go mod vendor 是因它破坏可重现性：vendor 目录易未提交或缓存污染，且不校验 go.sum 哈希；CI 应信任 go.mod + go.sum，统一 GOPROXY 并清理模块缓存。
go mod vendor 为什么在 CI 中常被禁用
CI 环境默认应复现开发环境的依赖状态，而 go mod vendor 会把模块复制进 vendor/ 目录，导致 go build 默认启用 vendor 模式（需 -mod=vendor 显式控制）。一旦本地忘记提交更新后的 vendor/，或 CI 缓存了旧 vendor，构建就可能使用不一致的依赖版本。
更关键的是：go mod vendor 不保证可重现性——它会拉取 replace 或 exclude 之外的最新兼容版本（如 indirect 依赖），且不校验 go.sum 中记录的哈希。CI 应该信任 go.mod + go.sum，而非人工维护的 vendor 目录。
- CI 流水线中应始终设置
GOPROXY=https://proxy.golang.org,direct，避免因网络或私有仓库不可达导致失败 - 禁止在 CI 脚本中执行
go mod vendor，除非项目明确要求离线构建且已通过go mod vendor -v+git diff --quiet vendor/验证一致性 - 若必须用 vendor，应在 PR 检查中加入
git status --porcelain vendor/，确保变更被显式提交和审查
go.sum 不匹配导致 CI 失败的典型场景
go.sum 是 Go 模块校验的核心，CI 中常见失败是：本地 go build 成功，但 CI 报 verifying github.com/some/pkg@v1.2.3: checksum mismatch。这通常不是网络问题，而是依赖源不一致或缓存污染。
根本原因包括：GOPROXY 设置不同（比如本地用了私有 proxy，CI 用官方 proxy）、GOINSECURE 绕过校验后未清理、或 go mod download 前未清空 $GOCACHE 导致复用错误哈希。
- CI 启动时应运行
go clean -modcache，避免复用历史下载的 module zip 或校验数据 - 确保所有环境使用相同
GOPROXY，私有模块必须配置GONOSUMDB或提前go mod download并校验go.sum - 不要手动编辑
go.sum；新增依赖后，用go get xxx@version或go mod tidy自动更新
多模块仓库（monorepo）中 go mod init 的路径陷阱
在含多个 service 或 cmd 子目录的仓库里，CI 构建某个子模块时若在错误路径下执行 go mod init，会导致模块路径与实际 import 路径不一致，引发 import cycle 或 cannot find module providing package 错误。
例如：仓库根目录为 github.com/org/repo，而 cmd/app 下执行 go mod init app，则其他地方 import "github.com/org/repo/cmd/app" 就无法解析——因为模块名是 app，不是完整路径。
- 每个
go.mod文件的模块名必须与代码实际被 import 的路径完全一致（大小写、斜杠、版本后缀都不能错） - CI 构建前应先
cd到对应子模块目录，再确认go list -m输出是否符合预期 - 避免在 CI 中动态生成
go.mod；模块初始化应在开发阶段完成，并提交到 git
Go 1.18+ 的 workspace 模式对 CI 的隐性影响
go.work 文件支持跨多个模块协同开发，但它**不会被 go build 自动识别**，除非显式启用 -work 标志或设置 GOWORK 环境变量。CI 中若未处理，会导致本地能跑通的 multi-module 修改在 CI 失败。
典型表现是：修改了 lib/ 模块，然后在 cmd/ 中直接引用未发布版本，本地用 go run 正常，CI 却报找不到符号或版本冲突——因为 CI 没读 go.work，仍从 proxy.gol 拉旧版。
ang.org
- CI 中不建议使用
go.work进行构建；它更适合本地快速验证，正式构建应基于go.mod的语义化版本 - 若必须用 workspace，CI 脚本需显式设置
GOWORK=go.work，并确保go.work中的use路径在 CI 工作区中存在且可读 -
go.work不参与go.sum校验，其中的replace会绕过校验逻辑，CI 中应避免用它替代go.mod的replace
模块管理的细节在 CI 中会被放大：一个本地忽略的 go.sum 更新、一次误用的 go mod vendor、或一个没对齐的模块路径，都可能导致构建结果不可重现。这些不是“配置问题”，而是 Go 模块系统对确定性的硬性要求——CI 必须比本地更严格地执行它。
