go.work 本地联调版本不生效：定位 GOWORK、use 与模块选择结果

多模块仓库里，明明已经把本地模块写进 go.work，联调时却像没有生效，最常见的原因不是代码没保存，而是当前命令根本没用你以为的工作区，或者本地模块命中了但依赖版本仍由另一套构建列表决定。排查顺序应该固定为：先看 GOWORK，再看 use 和 GOMOD，最后对照工作区构建列表与 CI 的单模块边界。

先用 go env GOWORK 证明当前命令是否进入工作区模式；只有确认工作区文件和 use 路径都命中后，才有必要讨论版本选择。

go 命令为什么拿错了 go.work

go 命令判断工作区，第一眼看的就是 GOWORK。它被设为 off 时，当前命令按单模块方式处理；它为空或未设置时，命令会从当前目录一路向父目录搜索 go.work；如果变量直接指向一个存在的 .work 文件，才会使用那一份工作区。

所以“我在仓库根目录放了 go.work”并不能证明联调会命中它。编辑器打开的目录、脚本的工作目录和 CI 的 checkout 目录只要不同，搜索结果就可能不同。排查时把当前工作目录也记下来，先别急着改 go.mod，把实际路径打印出来。

先确认 go 命令到底用了哪一个工作区

在需要联调的模块目录执行下面两条命令：

go env GOWORK
go env GOMOD

第一条应返回正在使用的 go.work 绝对路径；空行表示当前不是工作区模式。第二条返回当前包所属的 go.mod，它能帮助你确认命令没有落到旁边的测试模块或父目录模块。

接着打开这份 go.work，逐项核对 use 路径。use ./service 指向的是包含 go.mod 的模块根目录，并不会自动把更深层的嵌套模块一起加入。若仓库里有符号链接，也要注意 Go 的 use 路径匹配不会把链接路径和真实目标当成同一条路径。

为什么 use 能命中本地模块却仍不是你想要的版本

use 解决的是“哪些磁盘上的模块作为工作区主模块”这个问题，不是“每个依赖都采用哪个版本”。进入工作区后，Go 会把这些模块的 go.mod、其中的 go.mod require 要求与传递依赖合并成工作区构建列表，并按最小版本选择规则确定模块版本。因此，本地模块路径命中了，某个外部依赖却仍保持较高版本，并不矛盾。

排查时可以先看模块清单：

go list -m all

如果工作区里的 replace 规则覆盖了模块自己的同范围替换，也要把它列入判断。这里要区分三件事：主模块是谁、go.mod 要求了什么、工作区构建列表最后选了什么。只改 use，不一定会改变第三件事。

把本地联调结论带回 CI 和发布边界

本地联调可以明确指定工作区，例如在仓库脚本中使用 GOWORK=/path/to/dev.work，这样不会因为当前目录变化而读到父目录的另一份文件。要验证模块发布后真实的单模块行为，则使用 GOWORK=off go list -m all，把工作区因素排除掉。

是否提交 go.work 要看仓库是否始终把这些模块作为一个整体开发。Go 官方文档提醒，提交的工作区可能覆盖开发者自己的工作区，也可能让 CI 选择错误的依赖版本。更稳妥的做法是把两种检查都放进流程：工作区模式验证联调，GOWORK=off 验证独立模块的发布边界，并把差异记录在构建日志里。

go.work 常见问题：三个容易误判的边界

为什么 go env GOWORK 返回空？

空值表示当前命令没有进入工作区模式。检查变量是否被设为 off，再确认当前目录及父目录是否存在可用的 go.work。

go work use 为什么没有加入嵌套模块？

use 参数对应的是一个模块根目录，不会递归发现其子目录中的其他模块；需要递归时使用 go work use -r，并复查生成的路径。

本地工作区能通过，为什么发布构建失败？

发布构建可能没有使用同一份 go.work。先在 CI 打印 go env GOWORK，再用 GOWORK=off 复现，通常能快速确认是否把本地替换当成了发布依赖。