通过 go work sync 对齐工作区构建列表与模块依赖

多模块 Go 项目里，go.work 让多个本地模块一起参与构建，但它不会自动把最终依赖版本写回每个模块。需要把工作区解析出的依赖集合同步到各模块时，使用 go work sync。它基于 workspace build list 和最小版本选择（MVS）计算结果，再更新工作区中相关模块的 go.mod；它不是 go mod tidy 的别名，也不是主动升级依赖的替代命令。

先区分工作区构建列表与单模块依赖文件

go.work 中的 use 指令只是声明“哪些模块在一起工作”。这些模块作为多个 main module 参与解析后，Go 会形成一个 workspace build list，它包含构建所需的直接和传递依赖版本。工作区中的模块可能各自记录了不同版本，这正是需要对齐的场景。

go work sync 先根据 MVS 得到工作区使用的版本，再把与每个模块相关的依赖升级到该构建列表版本。它解决的是“同一工作区如何落回多个 go.mod”，而不是把所有未使用依赖统统删除。

用 go work use 维护参与构建的模块集合

同步前先检查 go.work 的边界。模块没有被 use 纳入时，go work sync 不会替它处理；把不相关的目录加入工作区，也会让构建列表和写回范围扩大。

# 初始化一个包含两个模块的工作区
go work init ./service ./shared

# 已有 go.work 时补充模块目录
go work use ./tools

# 递归寻找子目录中的 go.mod，并加入工作区
go work use -r ./modules

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

这里的关键不是命令数量，而是 use 列表要和“需要一起开发、测试或本地替换”的模块一致。发布模块时仍应回到单模块语境检查可复现性，不能把本地工作区状态当成版本发布流程。

运行 go work sync 并检查 go.mod 变化

确认工作区成员后，在包含 go.work 的目录运行同步命令：

# 按工作区构建列表把相关依赖版本同步回各模块
go work sync

# 查看哪些模块文件被改动，先保留差异再决定是否提交
git diff -- service/go.mod shared/go.mod

# 查看工作区解析出的模块版本，辅助确认统一结果
go list -m all

如果 go.mod 出现变化，先看差异中的模块名和版本，不要直接用 go mod tidy 覆盖结果。同步通常只会把模块要求提升到工作区构建列表对应的版本；它不会凭空替换成一个与当前图无关的最新版本。若变化来自错误的 use 路径、过期的 replace 或某个模块自身声明的更高 Go 版本，应先修正工作区边界或模块配置。

按任务选择 sync、tidy 或 get

这三个命令都可能改变依赖文件，但触发原因不同。先按目标选择，可以减少无关改动：

例如，工作区里一个模块引入了新依赖，另一个模块也需要在相同构建图上编译，先修正 use 集合，再运行 go work sync。如果只是某个模块删除了 import 后留下无用记录，则在该模块目录单独运行 go mod tidy。如果要升级到明确版本，则使用 go get example.com/lib@v1.2.3，并把升级理由留在变更记录里。

常见问题

go work sync 会把所有模块升级到最新版本吗？

不会。它依据当前工作区构建列表和 MVS 对齐版本，不等同于“查询并升级全部依赖”。需要主动升级时，应明确使用 go get。

运行 sync 后没有任何 go.mod 变化正常吗？

正常。若各模块已经满足当前 workspace build list，写回就没有必要。可以用 go env GOWORK 和 go list -m all 先确认确实处于目标工作区。

go work sync 能替代 go mod tidy 吗？

不能。sync 关注工作区版本向模块回写，tidy 关注单模块源码与测试对应的依赖集合；它们的判断范围不同。