Go workspace 里 replace 生效但单模块构建失败怎么办

在多模块仓库里，go work 下能编译，并不等于任意一个子模块脱离 workspace 后也能编译。最常见的现场是：go.work 里的 replace 明明指向了本地模块，根目录执行 go build 正常；进入某个子目录，使用 GOWORK=off go build ./... 却提示找不到包、版本不匹配，甚至报 module ... does not contain package ...。

先把问题拆成“命令是否在 workspace、replace 作用于哪个主模块、被替换模块是否被 require”三层。workspace 只改变当前命令的主模块集合；它不会自动把每个子模块的依赖声明改写成可独立发布的 go.mod。

先确认失败命令到底在哪个模块里

不要先改 replace。先在报错目录执行下面几条命令，记录当前主模块和 workspace 文件：

# 先确认 go 命令是否加载了父目录中的 go.work
go env GOWORK

# 查看当前目录所属的单模块 go.mod
go env GOMOD

# 显示 workspace 中参与构建的主模块
go list -m -f '{{.Path}} main={{.Main}} dir={{.Dir}} replace={{if .Replace}}{{.Replace.Dir}}{{end}}' all

GOWORK 返回空值表示当前没有启用 workspace；返回 off 则是被显式关闭；返回文件路径才说明本次命令使用了对应的 go.work。如果开发机从仓库根目录构建，而 CI 进入子模块后设置了 GOWORK=off，两边看到的主模块集合本来就不同。

workspace 的 replace 到底覆盖了什么

假设仓库结构如下：app 是当前服务，lib 是本地库，二者各有自己的 go.mod：

repo/
├── go.work
├── app/go.mod
└── lib/go.mod

go.work 的 use ./app 和 use ./lib 会把两个模块都纳入 workspace。只要 app 导入的包路径和 lib/go.mod 的 module 声明一致，workspace 通常可以直接使用本地源码。若再写：

// go.work 不是 Go 源码，这里展示 workspace 文件中的关键声明。
go 1.23

use (
    ./app
    ./lib
)

// 仅在这个 workspace 的模块解析上下文中替换依赖内容。
replace example.com/lib => ./lib

这个替换优先影响 workspace 构建；它不会把 replace 自动复制到 app/go.mod。Go 官方模块参考也明确说明，workspace 中的替换可以覆盖 workspace 模块里同模块的替换，但离开该 workspace 后，单模块命令仍按自己的 go.mod 解析。

检查 require、module 路径和本地目录三件事

单模块构建失败时，优先查下面三个连接点：

# 在 app 目录查看 go.mod 的声明，避免把 workspace 结果当成单模块结果
cd app
go mod edit -json

# 强制不读取 go.work，观察 app 自己能否解析依赖
GOWORK=off go list -m -json example.com/lib
GOWORK=off go build ./...

官方规则里，单独的 replace 不会把模块加入依赖图；它必须对应一个 require。右侧使用本地路径时，目标目录必须含 go.mod，且其中的 module 路径要与左侧被替换模块匹配。这个检查能解释很多“workspace 正常、子模块失败”的现象。

用两种构建结果决定修复位置

把结果分成两类更容易做决定：

• 只有 workspace 构建需要本地联调：保留 go.work 的 use，必要时保留 workspace 级 replace；发布前用独立目录或 GOWORK=off 验证。
• 子模块本身也必须可复现构建：把正式依赖版本写入子模块的 require，临时本地开发替换放在该模块的 go.mod，并避免提交依赖某个仓库外相对目录的路径。

一个更稳妥的回归顺序是：先在 app 目录执行 GOWORK=off go build ./...，再回到仓库根目录执行 go build ./app/...。前者验证可独立发布，后者验证多模块联调。两者的依赖目标不同，不能只通过一次成功的根目录构建下结论。

常见问题

为什么只写 go.work 的 replace 不够？

因为它服务于当前 workspace。离开 workspace 或设置 GOWORK=off 后，命令只看当前主模块及其依赖声明；没有 require 的替换也不会进入模块图。

GOWORK=off 一定会让本地模块不可用吗？

不一定。如果当前模块自己的 go.mod 已经有正确的 require 和本地 replace，单模块构建仍可使用本地模块；否则就会回到模块代理或版本缓存中寻找依赖。

应该把 replace 提交到仓库吗？

如果它只是本地联调路径，通常放在开发用 workspace；如果团队明确需要稳定的本地模块组合，则要评估相对路径对 CI、发布和其他开发者目录的影响，并把独立构建作为合并前检查。