go work sync 统一多模块版本校准的操作清单

多模块仓库里，go work sync 不是把一个 go.mod 原样复制到其他目录，而是先根据 go.work 中 use 的模块计算工作区 build list，再把相关依赖版本写回这些模块。它适合用来收敛联调后的依赖基线，但不能替代每个模块的独立构建检查。

官方地址：https://go.dev/ref/mod#go-work-sync

先确认 go.work 真正覆盖了哪些模块

同一个仓库可能存在多个 go.work，Go 还会从当前目录向父目录查找。第一条检查命令不是同步，而是确认上下文：

# 查看当前 go 命令实际采用的工作区文件
go env GOWORK

# 从工作区根目录查看模块入口和 replace 关系
sed -n '1,160p' go.work

如果输出为空，当前命令处于单模块模式；如果输出是 off，则明确关闭了工作区。只有输出了预期的 go.work 路径，才适合继续检查 use 列表。缺少模块时，先用 go work use ./path/to/module 补入，不要指望 go work sync 自动发现仓库中的所有 go.mod。

go work sync 怎样完成版本校准

确认模块集合后，在 go.work 所在目录执行同步：

# 根据 workspace build list 计算并写回 use 指定模块
go work sync

# 只查看同步涉及的文件差异，避免把源码改动混在一起
git diff -- go.work go.work.sum services/api/go.mod services/api/go.sum \
  libs/common/go.mod libs/common/go.sum

它采用最小版本选择（MVS）计算工作区依赖图，然后顺序检查每个模块的依赖要求。某个模块需要的版本低于工作区 build list 时，go.mod 会被升级到 build list 的版本；因此这个命令的核心效果是“向统一基线靠拢”，不是任意降级。go.work.sum 还可能记录工作区模块的 go.sum 尚未包含的校验和。

把工作区结果和单模块结果分开验证

工作区能让本地模块互相使用，尤其适合跨模块联调；但发布时，模块应当能按照自己的 go.mod 被构建。建议保留两种语境的检查：

# 工作区语境：确认本地模块之间的联调路径可用
go test ./...

# 单模块语境：关闭 go.work，检查模块是否能独立解析依赖
GOWORK=off go test ./...

第二条命令要在具体模块目录执行，或者由 CI 对每个模块分别执行。若只有工作区语境成功，通常说明测试依赖了 use 的本地模块或 go.work 的 replace，这时不应直接把“同步成功”当作可发布结论。

提交前的四项落地清单

• 确认所有 use 路径都指向真正包含 go.mod 的目录，路径不要只靠个人目录结构成立。
• 逐个查看 go.mod 差异，确认版本提升与本次模块改动有关。
• 把 GOWORK=off 的模块测试纳入 CI，尤其是需要单独发布的模块。
• 谨慎提交 go.work：如果仓库服务多个独立消费者，提交它可能让 CI 误用本地模块组合；如果仓库只为内部模块协同开发，则可以明确记录提交理由。

常见问题

go work sync 会把所有模块的依赖完全改成一样吗？

不会。它统一的是工作区 build list 中相关依赖的版本，各模块仍只保留自己需要的依赖；MVS 也只保证选出的版本不低于各模块已有要求。

为什么执行后某个 go.mod 没有变化？

可能是该模块没有需要升级的依赖，也可能它不在当前 go.work 的 use 列表中。先用 go env GOWORK 和 go.work 核对范围。

go work sync 能替代 go mod tidy 吗？

不能。go work sync 面向工作区 build list；go mod tidy 面向单个主模块的依赖整理。二者应按模块发布流程分别使用。