go work vendor 结果不一致的依赖同步步骤

我第一次在多模块仓库里遇到 inconsistent vendoring 时，直觉是删掉 vendor 再跑一遍命令。后来发现，真正需要同步的不是一个目录，而是三层状态：go.work 定义的工作区、各模块的 go.mod，以及工作区根目录中的 vendor/modules.txt。只重建最后一层，常常会把前两层的分歧原样带回来。

我现在采用的判断是：先确认 Go 命令正在使用哪个工作区，再决定是否需要 go work sync；逐个模块整理依赖后，最后只运行一次 go work vendor。不要手工编辑 vendor/modules.txt，也不要在工作区模式下用 go mod vendor 代替它。

官方参考：https://go.dev/ref/mod#workspaces、https://pkg.go.dev/cmd/go。工作区级 vendor 从 Go 1.22 开始得到正式支持；工作区根目录存在 vendor 时，构建命令默认会使用它。

先保护真正重要的东西：工作区构建列表

把这类问题当成供应链一致性问题会更容易理解。需要保护的“资产”不是 vendor 文件数量，而是所有工作区模块在同一次构建中看到同一组依赖版本与替换规则。

• go.work 的 use 决定哪些模块属于当前工作区。
• go.work 的 replace 会覆盖各模块中的替换规则。
• 每个模块的 go.mod 保存该模块自己的最低依赖要求。
• 工作区构建列表由全部主模块共同参与最小版本选择得到。
• vendor/modules.txt 是 vendor 内容的清单，也是 Go 检查显式依赖、版本和替换关系是否一致的依据。

Go 官方文档说明，go work vendor 会重置工作区 vendor，使其包含构建和测试工作区全部包所需的依赖包，但不会包含被 vendor 依赖自身的测试代码。这也是为什么不同模块分别执行 go mod vendor，结果不能等价于一次工作区级生成。

我先确认当前命令到底落在哪个工作区

我碰到过最隐蔽的一类问题，是终端目录看起来在仓库内，但上层目录还藏着另一个 go.work。Go 会向父目录查找工作区文件，因此第一步应读取命令真实采用的环境，而不是凭目录名猜。

# 显示当前 Go 命令实际使用的工作区文件
go env GOWORK

# 查看当前工具链版本，工作区 vendor 需要 Go 1.22 或更高版本
go version

# 输出工作区配置，核对 use 与 replace 的真实内容
go work edit -json

如果 go env GOWORK 为空，说明没有进入工作区模式；如果它指向意料之外的文件，应先切换目录或显式设置正确的 GOWORK。如果项目实际只想维护一个模块，可以用 GOWORK=off 退出工作区模式，再处理单模块 vendor，但这已经是另一条构建契约，不能和 workspace vendor 混在同一次提交里。

三类不一致分别意味着什么

官方 Go 源码测试覆盖了几类典型错误。我通常按风险从高到低处理：

临时使用 -mod=mod 或 -mod=readonly 可以绕开 vendor 继续诊断，但它不是修复。前者改为从模块缓存或网络解析依赖，后者禁止修改 go.mod；两者都没有让仓库中的 vendor 重新可信。如果 CI 的目标是离线或可审计构建，最终仍要回到 -mod=vendor 验证。

依赖同步的稳妥步骤

我的同步顺序不是每次机械执行全部命令，而是先看哪些源文件应该变化。go work sync 会用最小版本选择生成工作区构建列表，并把更高版本同步回 use 中的模块；官方说明这种同步只会把依赖升级到工作区选中的版本。因此执行前应准备审查各模块 go.mod 的变化。

# 第一步：把工作区构建列表同步回所有 use 模块
go work sync

# 第二步：进入每个主模块，清理该模块实际需要的依赖
cd services/api
go mod tidy
cd ../worker
go mod tidy
cd ../..

# 第三步：回到 go.work 所在目录，统一生成 workspace vendor
go work vendor

# 第四步：强制使用 vendor 加载工作区中的全部包
go list -mod=vendor ./...

如果团队不希望 go work sync 自动更新模块要求，可以先只运行 go work vendor 看错误是否消失；但一旦多个模块对同一依赖版本存在分歧，我更愿意显式同步并审查差异，而不是让工作区构建时选中较高版本、单模块构建时又回到较低版本。

go mod tidy 始终针对单个主模块，不能在工作区根目录“一次整理所有模块”。模块很多时可以用仓库脚本逐个进入目录，但脚本仍应让每次失败可见，不能把错误吞掉。

为什么不能在工作区里改用 go mod vendor

从 Go 1.22 起，工作区模式中执行 go mod vendor 会直接提示：要么运行 go work vendor 为整个工作区生成依赖，要么设置 GOWORK=off 退出工作区模式。这个限制很合理，因为同一个目录中的 vendor 不可能同时代表“某个模块的依赖闭包”和“整个工作区的依赖闭包”。

我会在仓库 README 中明确写清 vendor 的所有者：

• 工作区仓库：根目录 vendor 只由 go work vendor 生成。
• 独立模块仓库：模块根目录 vendor 由 go mod vendor 生成。
• 既要工作区开发又要模块独立发布：发布流水线用 GOWORK=off 单独验证模块，不复用工作区 vendor。

把一致性变成 CI 门禁

同步成功并不代表以后不会漂移。最有效的控制是让 CI 重新生成并检查 Git 差异，再强制从 vendor 构建。这样新增 require、删除 replace 或修改 use 后，提交者会立即看到 vendor 是否需要更新。

# 重新生成工作区供应目录，确保清单来自当前 go.work 与 go.mod
go work vendor

# 生成后不应留下未提交差异
git diff --exit-code -- go.work '**/go.mod' '**/go.sum' vendor

# 强制从 vendor 编译和测试，避免网络或模块缓存掩盖缺失文件
go test -mod=vendor ./...

如果仓库包含嵌套模块，根目录的 ./... 不一定跨越所有模块边界。稳妥做法是依据 go.work use 列表逐个模块测试，或者维护一份明确的模块清单。重点不是命令越短越好，而是 CI 覆盖的模块集合必须与工作区声明一致。

我的取舍：哪些项目值得提交 vendor

对需要离线构建、依赖源受限、供应链审计严格或构建必须长期可复现的项目，我会提交 workspace vendor，并把上述检查作为合并门禁。代价是仓库体积增大、依赖升级的 diff 更大，而且每次 go.mod 或 go.work 调整都要同步生成物。

对普通内部服务，如果模块代理和校验数据库都稳定，我更倾向于不提交 vendor，而是依赖 go.sum 和受控代理。关键在于团队只能选一种明确契约：要么 vendor 是可信构建输入并持续验证，要么它根本不进入仓库。最麻烦的是保留一个长期不更新的 vendor，让开发机偶尔用模块模式、CI 偶尔又自动切到 vendor 模式。

最后检查清单

• go env GOWORK 指向预期的 go.work。
• 工具链为 Go 1.22 或更高版本。
• use 没有引用已删除或错误的模块目录。
• 工作区级 replace 与模块级替换没有意外冲突。
• 需要统一依赖版本时已审查 go work sync 带来的 go.mod 变化。
• 每个主模块分别运行并审查了 go mod tidy。
• vendor 只由 go work vendor 重建，没有手改 modules.txt。
• CI 使用 -mod=vendor 验证，并确认生成后没有 Git 差异。

这套步骤的核心不是“多跑几个命令”，而是按责任边界同步：工作区先统一版本视图，模块各自维护声明，vendor 最后作为派生产物一次生成。顺序清楚后，inconsistent vendoring 就不再是一个模糊报错，而是一条很具体的状态漂移提示。