Go go.work 的 use 路径如何影响依赖解析

同一个仓库里放着 app、shared 两个 Go 模块时，开发者常会把 go.work 的 use 理解成“把这棵目录树都加入依赖搜索”。实际并不是这样：use 的参数必须指向包含 go.mod 的模块目录，而且不会递归吸收它下面的其他模块。路径写得过高，结果可能是 workspace 没有纳入预期模块；路径写得过窄，则会漏掉另一个本地模块。

先看 GOWORK，别先改 go.mod

当 go.work 为空或没有设置时，Go 会从当前工作目录开始向父目录查找；找到后，命令就在该 workspace 中运行。先执行下面两条命令，能快速区分“当前模块没有替换依赖”和“根本没有进入 workspace”：

# 查看当前命令实际使用的 workspace 文件；空值表示单模块模式
go env GOWORK

# 查看当前目录对应的主模块与完整模块列表
go env GOMOD
go list -m -json all

如果输出的 GOWORK 指向仓库上层，说明你可能继承了父目录配置。只想临时验证发布语义时，可以使用 GOWORK=off go list -m all，它不会读取 workspace 中的本地模块集合。

use 路径只认模块根，不会递归穿透

假设目录如下：

# 仓库目录结构（每个 go.mod 都代表一个独立模块）
repo/
  go.work
  app/go.mod
  shared/go.mod
  examples/demo/go.mod

若 go.work 只有 use ./app，它只纳入 app。即便 app 目录未来再放入 plugins/foo/go.mod，也不会因为父路径已被 use 而自动纳入；嵌套模块必须单独写 use ./app/plugins/foo。实务上，最稳妥的写法是让每个参与联调的 go.mod 都有一个明确的 use 行：

go 1.23.0

use (
    ./app       // 主服务模块
    ./shared    // 被主服务引用的本地模块
)

用模块列表判断本地模块是否真的生效

不要只看 go.work 文本判断依赖是否切换。执行 go list -m -json all 后，重点看目标模块的 Main、Dir 和 Path：本地 workspace 模块通常带有本机目录信息，且会作为主模块参与构建。可以用下面的筛选方式缩小输出：

# 只打印模块路径、目录和 Main 标记，便于核对本地覆盖关系
go list -m -json all | grep -E '"Path"|"Dir"|"Main"'

如果 shared 仍指向模块缓存，先检查三件事：use 是否写到了含 shared/go.mod 的目录；命令执行目录是否落在该 go.work 的作用范围内；是否设置了 GOWORK=off。这比盲目删除 go.sum 更接近真实原因。

本地联调和 CI 构建要分开看

go.work 很适合多个本地模块同步开发，但它会让当前目录优先使用工作区里的源码。官方文档也提醒，提交 go.work 可能让 CI 选择错误的依赖组合。因此团队可以保留本地 workspace，却在 CI 的构建命令前显式写出：

# CI 按单模块消费者的方式构建，不读取父目录或仓库中的 go.work
GOWORK=off go test ./...
GOWORK=off go build ./...

这样做的边界很清楚：本地用 use 加快联调，发布前用单模块模式验证依赖是否已正确声明和发布。不要把 GOWORK=off 当成修复工具，它只是帮助你确认问题是否来自 workspace 覆盖。

常见问题

use 写仓库根目录为什么没有纳入所有模块？

因为 use 的参数对应一个模块目录，只读取该目录中的 go.mod，不会递归寻找子目录里的其他 go.mod。

如何知道当前命令用了哪个 go.work？

执行 go env GOWORK；它会返回实际文件路径，空值则表示当前不是 workspace 模式。

go.work 一定要提交到 Git 吗？

不一定。多个模块长期一起开发且组合固定时可以提交；否则更适合让开发者本地维护，并在 CI 显式关闭 workspace。