Go work sync 为什么不会自动改写 go.mod

很多人第一次使用 Go workspace 时会发现：执行 go work sync 后，当前模块的 go.mod 没有任何变化。通常这不是命令失效，而是把“工作区依赖同步”和“单模块依赖整理”混成了一件事。

先说结论：go work sync 根据 go.work 定义的工作区生成构建列表，再把其中需要的模块版本同步到 use 指向的各个主模块；如果当前命令没有进入工作区、依赖没有改变，或者你期待的是清理单模块依赖，它都可能看起来像“没有改写”。

官方资料：https://go.dev/ref/mod#workspaces

先确认命令是否进入工作区模式

Go 命令先看 GOWORK。它被设置为 off 时会强制关闭 workspace；为空时，Go 会从当前目录向父目录查找 go.work。因此，目录里明明有一个工作区文件，命令也不一定正在使用它。

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

# 在工作区文件所在目录查看模块集合
go work edit -json

# 只在确实需要单模块行为时临时关闭 workspace
GOWORK=off go list -m all

go env GOWORK 如果为空，表示当前不在 workspace 模式；如果显示 off，则是显式关闭；只有它指向一个实际的 .work 文件时，后续的工作区命令才有明确输入。还要继续看 go.work 的 use 列表，当前目录不在这些模块中时，修改目标也不会是你以为的那个 go.mod。

go work sync 和 go mod tidy 解决的不是同一个问题

工作区由多个本地模块组成。go work sync 面对的是这些模块合在一起参与构建时的依赖版本集合；go mod tidy 则始终针对单个主模块，根据该模块的源码导入关系整理 go.mod 和 go.sum。

所以，如果你的问题是“某个模块源码已经不再导入某个库，为什么 go.mod 还有它”，应先运行该模块目录下的 go mod tidy；如果问题是“多个本地模块应该使用同一组依赖版本，怎样把工作区决定的版本同步回去”，才使用 go work sync。

sync 为什么执行了却没有可见变化

命令执行后文件不变，常见原因有四类。第一，工作区构建列表与各模块当前声明的版本已经一致，sync 是幂等的，不会为了制造差异而改文件。第二，当前目录没有使用目标 go.work，例如环境变量指向了另一个文件或被设为 off。第三，目标模块没有放进 use，sync 不会替你把新模块加入工作区。第四，构建列表中的依赖只来自工作区实际参与构建的模块，未参与构建的源码目录不会凭空成为依赖。

package main

import "fmt"

func main() {
	// 这个程序只用于说明模块关系：真正的依赖选择由 go.work 和 go 命令完成。
	fmt.Println("workspace dependency boundary")
}

排查时可以把动作拆开：先用 go env GOWORK 确认输入，再打开 go.work 查看 use，然后分别进入每个模块运行 go list -m all 对比依赖集合。不要把“文件没有变化”直接当成失败信号，它也可能说明同步结果本来就已经一致。

按症状选择正确的修复命令

可以用下面的最小判断来避免反复尝试：

• 想增加本地模块：用 go work use ./path/to/module，改变的是 go.work。
• 想让工作区版本回写到所有主模块：确认 GOWORK 和 use 后运行 go work sync。
• 想按当前模块源码清理依赖：进入该模块目录运行 go mod tidy。
• 想模拟模块被外部单独使用：用 GOWORK=off 执行构建或测试，避免本地工作区覆盖真实依赖选择。

最后记住一个边界：go.work 是工作区协作文件，不是所有模块发布时都会携带的依赖清单。团队是否把它提交到版本库，还要结合仓库是否始终以这些本地模块组合开发；CI 通常需要明确是否关闭 workspace，避免测试到了本地工作区特有的版本。

常见追问

go work sync 会修改 go.work 吗？

它的职责是把工作区构建列表同步到各个 use 模块，增加或删除模块应使用 go work use 或编辑工作区文件。

为什么 go work sync 后只有部分 go.mod 变化？

因为写回对象是工作区中的主模块，而且只有依赖版本实际不同的模块才需要产生文件差异；其他模块保持不变是正常结果。