Go workspace sync 怎样保持多个模块的依赖版本一致

多个 Go 模块放在同一个仓库里联调时，最容易出现的不是“依赖完全不同”，而是同一个依赖在不同模块的 go.mod 中停留在不同版本。稳妥的做法是：先用 go.work 明确参与联调的模块，再从工作区根目录执行 go work sync，让 workspace build list 经过 MVS 计算后回写到各模块；发布或 CI 阶段再用 GOWORK=off 检查每个模块能否独立成立。

先把真正需要联调的模块放进 go.work

假设仓库有 api、worker 和 shared 三个模块。不要为了“看起来完整”把整个仓库递归加入工作区；先列出实际需要同时修改的模块：

# 在包含多个模块目录的仓库根目录创建工作区
go work init ./api ./worker ./shared

# 查看当前 Go 命令实际使用的 go.work 文件
go env GOWORK

# 只在确实需要扫描子目录中的模块时使用递归加入
go work use -r ./modules

go.work 的 use 指令提供了本地模块边界。执行构建、测试或 go list 时，Go 会先根据 GOWORK 决定是否进入 workspace 模式；如果环境变量为空，命令会从当前目录向父目录查找 go.work。因此，排查版本漂移的第一步不是改版本，而是确认命令是否真的读到了预期的工作区。

go work sync 具体同步了什么

工作区构建列表包含所有参与构建的直接和传递依赖版本。go work sync 使用最小版本选择（MVS）生成这个列表，然后把各模块中与自身相关的依赖要求同步到这个版本。它解决的是“同一工作区怎么得到一致的解析结果”，不是把每个模块的依赖清单复制成同一份。

# 以 go.work 中的模块集合计算并回写工作区依赖版本
go work sync

# 查看工作区解析出的完整模块版本集合
go list -m all

# 只检查同步命令实际改动了哪些依赖声明和校验文件
git diff -- go.mod go.sum go.work go.work.sum

如果 api 需要 example.com/log v1.4.0，而 worker 需要 v1.6.0，MVS 会以工作区构建所需的较高版本作为解析结果。同步后，相关模块的 go.mod 可能出现版本提升；这并不代表所有模块都必须新增同样的 require 行。go.work.sum 则用于保存工作区需要、但各模块 go.sum 尚未覆盖的校验信息。

同步之后仍要按模块整理 go.mod

go work sync 和 go mod tidy 的职责不同。前者以工作区构建列表为基准做版本回写，后者针对一个主模块整理直接依赖、间接依赖和无用条目。若某个模块的源码刚改过，建议进入该模块单独整理，再回到根目录确认工作区结果：

# 进入一个模块，按它自己的源码引用整理依赖
cd api
go mod tidy

# 回到工作区根目录，再观察多个模块的最终差异
cd ..
go work sync
git diff --stat -- api/go.mod api/go.sum worker/go.mod worker/go.sum

这里的判断标准是“每个模块都能解释自己的依赖”，而不是追求所有 go.mod 文本完全相同。若同步后发现某模块只在本地工作区能编译，通常是把本地 use 带来的替换关系误当成了已发布版本；这时应关闭 workspace 再测一次。

提交 go.work 前先划清本地与 CI 边界

Go 官方文档提醒，直接把 go.work 提交到版本库可能让开发者自己的工作区被覆盖，也可能让 CI 误用本地模块组合。若仓库中的模块始终一起开发、一起发布，提交它可以是明确的工程决策；否则更适合把它作为本地联调文件，并在 CI 中显式关闭：

# 在 CI 中关闭父目录或仓库内的 go.work，验证模块自己的声明
GOWORK=off go test ./...

# 多模块仓库应逐个进入模块执行同样的独立检查
for module in api worker shared; do
  (cd "$module" && GOWORK=off go test ./...)
done

提交前可以按下面的清单判断：

常见问题

go work sync 会把所有模块的 go.mod 改成一样吗？

不会。它把工作区构建列表中与各模块相关的依赖版本回写进去；不同模块仍可保留不同的直接依赖集合。

为什么本地能编译，GOWORK=off 后失败？

通常是本地 use 让导入解析到了另一个工作区模块，独立模块的 go.mod 尚未声明可用版本。应在独立模式下补齐模块发布依赖，而不是把 CI 永久绑定到本地工作区。

同步后还需要 go mod tidy 吗？

需要时仍然需要。go work sync 解决工作区版本基准，go mod tidy 负责某个模块的源码依赖整理，两者不是替代关系。