Go work sync 维护多模块工作区依赖

当一个 go.work 同时引用多个模块，而这些模块对同一依赖声明了不同版本时，go work sync 会先用最小版本选择（MVS）计算工作区构建列表，再把与各模块相关的版本同步回对应的 go.mod。它解决的是“工作区里实际构建的版本”和“模块文件里声明的版本”逐渐分离的问题，但不会代替每个模块自己的 go mod tidy。

官方参考：https://go.dev/ref/mod#go-work-sync

一、特性解决什么：工作区能构建，模块单独构建却不一致

假设仓库中有 app、lib 和 service 三个模块。app 对某个依赖声明较低版本，lib 声明较高版本。启用工作区后，Go 会把这些模块都视为主模块，并为整个工作区计算一份构建列表。MVS 保证该列表中的依赖版本不低于任一工作区模块声明的版本。

这意味着在工作区中运行测试可能一直成功，但关闭工作区模式后，某个模块仍按自己的旧 go.mod 构建，结果可能不同。go work sync 的作用就是把工作区已经选中的相关版本回写给各模块，缩小这两种上下文的差异。

二、work sync 同步的到底是什么

use 指令决定哪些本地模块进入工作区。go work sync 读取这些模块的需求，通过 MVS 得到整个工作区的构建列表，然后逐个处理工作区模块：如果模块对某依赖的版本低于工作区选中的版本，就把该模块中相关依赖升级到工作区版本。

“同步”并不等于把完整工作区依赖集合原样复制到每个模块。官方说明强调，重写的是与该模块相关的依赖；因此执行后应审查每个 go.mod，确认变更确实来自模块需要，而不是把生成文件当成不可读的黑盒。

三、支持范围：先确认命令使用的是哪一个工作区

Go 1.18 起提供工作区模式。执行命令前，先确认当前目录向上查找到的 go.work 是否就是目标文件。环境变量 GOWORK 可以指定一个以 .work 结尾的文件，也可以设为 off 禁用工作区模式。

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

# 查看工作区声明，确认 use 中只有本次要维护的模块
go work edit -json

# 如需加入新的本地模块，先更新 go.work 的 use 指令
go work use ./service

目录大致可以是下面这样：仓库根目录保存 go.work，每个子目录都有独立的 go.mod。

workspace/
├── go.work          # 工作区入口
├── app/go.mod       # 应用模块
├── lib/go.mod       # 库模块
└── service/go.mod   # 服务模块

如果 go env GOWORK 指向父目录中的另一个文件，应先切换到正确目录，或显式设置目标工作区路径。否则一次看似正常的同步可能会修改意料之外的模块。

四、最小示例：同步后只接受预期的 go.mod 变化

在已经存在多个模块的仓库中，初始化或维护工作区后执行一次同步。下面的命令把“准备、同步、审查”放在同一个可复核的小闭环里。

# 首次创建工作区，并登记两个现有模块
go work init ./app ./lib

# 后续把第三个模块加入工作区
go work use ./service

# 用 MVS 计算工作区构建列表，并同步相关版本到各模块
go work sync

# 只审查本次可能变化的工作区与模块文件
git diff -- go.work go.work.sum app/go.mod lib/go.mod service/go.mod

审查时重点看三件事：是否只有预期依赖被升级；是否出现新的间接依赖；是否有模块因为工作区替换或高版本需求而获得了不准备发布的版本。如果改动超出预期，应回到各模块的依赖声明和 go.work 中的 replace 检查原因，而不是直接提交。

同步之后可以先在工作区内运行测试，再逐模块关闭工作区测试。后一个检查更接近模块被其他项目依赖时的真实状态。

# 在工作区上下文中运行全部模块相关测试
go test ./...

# 进入单个模块后关闭工作区，验证它能独立解析依赖和测试
cd app
GOWORK=off go test ./...

五、work sync 与 go mod tidy 的分工

go work sync 处理的是“工作区选中的版本如何反映到各模块”；go mod tidy 处理的是“单个模块的包和测试实际导入了什么，因此其 go.mod 与 go.sum 应保留什么”。两者输入和结果不同，不应互相替代。

对于准备发布的模块，可以在各模块目录中分别运行 go mod tidy，然后再次审查差异。不要只在仓库根目录运行一次就假定所有子模块都已整理，因为官方参考明确说明 go mod tidy 始终针对单个主模块。

六、兼容与 CI：同时检查工作区和单模块两种上下文

工作区适合本地联调，但它可能掩盖模块独立发布时的依赖问题。CI 可以分成两类任务：一类启用工作区，验证多模块协同；另一类对每个准备发布的模块设置 GOWORK=off，验证其独立的 go.mod 足以完成构建和测试。

# 确认同步后没有未提交的模块依赖变化
go work sync
git diff --exit-code -- app/go.mod lib/go.mod service/go.mod

# 分别验证模块不依赖本地工作区也能完成测试
(cd app && GOWORK=off go test ./...)
(cd lib && GOWORK=off go test ./...)
(cd service && GOWORK=off go test ./...)

是否把 go.work 提交到版本库要看协作模型。Go 官方通常不建议提交，因为它可能覆盖开发者父目录中的个人工作区，并让 CI 选中与模块消费者不同的依赖版本；但如果同仓模块只作为一个固定组合共同开发，提交也可能合理。关键是让团队规则、CI 环境和发布流程一致，而不是套用绝对结论。

七、性能与安全注意

依赖很多时，go work sync 需要加载并计算完整工作区模块图。不要把它无条件塞进每次编辑后的热循环；更合适的时机是新增模块、调整依赖版本、修改工作区替换规则或准备合并依赖变更之后。对私有模块，还要确保 CI 的 GOPRIVATE、代理和凭据配置符合团队安全策略，避免把令牌写入 go.work、go.mod 或日志。

同步属于会修改文件的操作。运行前确认工作区范围，运行后使用 git diff 查看实际变化，并让自动化通过 --exit-code 阻止遗漏的生成差异。这样才能把“本地能跑”变成可提交、可发布、可复现的依赖状态。

八、常见问题

1. go work sync 会更新 go.work 吗？

它的核心目标是计算工作区构建列表，并把相关版本同步回 use 指向模块的 go.mod。管理 go.work 中的模块列表应使用 go work use，低层编辑则使用 go work edit。

2. 为什么 sync 之后还要运行 go mod tidy？

因为 sync 关注跨模块的版本一致性，tidy 关注单个模块当前导入图需要保留哪些直接或间接依赖。模块准备独立发布时，两个检查都重要。

3. 为什么工作区测试通过，GOWORK=off 却失败？

常见原因是模块依赖了工作区中的本地模块、替换规则或更高依赖版本，但自己的 go.mod 尚不足以独立解析。先检查 go.work 的 use 与 replace，再检查该模块的依赖声明和发布版本。

4. 每次提交前都必须执行 sync 吗？

不必机械执行。只要依赖或工作区组成发生变化，就应同步并审查；团队也可以在 CI 中运行同步后用 git diff --exit-code 检查是否存在遗漏。