Go work use 加入本地模块后 CI 为什么找不到目录

本地执行过 go work use ../shared，开发机能导入 sibling 模块，并不代表 CI 也能找到它。最常见的原因是 CI 没有检出 go.work 或它指向的模块目录，或者流水线设置了 GOWORK=off。工作区里的 use 参数是相对路径，必须相对于 go.work 所在位置解析；只要 checkout 范围、工作目录或环境变量不同，结果就会不同。

官方文档：https://go.dev/ref/mod#workspaces

先问清 CI 要验证什么：内部多模块联调就让同一份仓库同时包含 go.work 和被 use 的模块；要模拟外部使用者，就关闭工作区，按目标模块自己的 go.mod 和已发布依赖构建。

先确认 go.work 与模块目录是否一起进入 CI

假设仓库结构如下：

repo/
  go.work
  app/go.mod
  shared/go.mod

在 repo 目录执行 go work use ./app ./shared 后，go.work 的 use 条目指向两个模块根目录。它不会递归地把所有子目录自动变成模块，也不会替 CI 下载缺失的本地目录。若流水线只检出 app，或使用 sparse checkout 排除了 shared，use ./shared 当然无法解析。

这里还有一个容易误判的细节：相对路径看的是 go.work 的位置，不是你在 CI 配置里写下命令的那一行。把工作目录从仓库根切到子目录本身不会改写 use ./shared 的含义，但可能让 Go 找不到上层的 go.work；Go 会从当前目录向父目录搜索，直到找到工作区文件或到达文件系统根。

确认 Go 命令实际启用了哪个工作区

不要只看仓库里有没有 go.work，在出错的同一个 CI 步骤中打印实际状态：

set -eu

# 显示流水线真正运行的位置，避免把本地目录当成 CI 目录。
printf 'pwd: '; pwd

# 检查工作区文件和本地模块根是否真的被检出。
test -f go.work
test -f app/go.mod
test -f shared/go.mod

# GOWORK 为空表示单模块模式，off 表示显式关闭工作区。
go env GOWORK
go env GOMOD

# 模块列表应能看到工作区中的本地模块。
go list -m all

如果 go env GOWORK 输出为空，先确认当前目录是否位于 go.work 所在目录树中；如果输出 off，说明环境变量主动关闭了工作区。go env GOMOD 则帮助确认当前命令属于哪个模块。若文件存在但模块列表仍不对，继续检查 CI 是否覆盖了 GOWORK、是否在另一个 checkout 目录运行，以及流水线是否为每个 job 使用了不同的工作目录。

按 CI 目标选择 workspace 或单模块模式

问题的关键不是“要不要永远提交 go.work”，而是构建语义。团队内部要同时修改 app 和 shared，可以把 go.work 放进仓库，确保 CI 完整检出它和所有 use 目标；这验证的是一组本地模块协同工作的结果。

但如果流水线要回答“别人安装已发布的 app 模块时能否正常构建”，就不应让开发机的 go.work 偷换依赖来源。官方模块参考也提醒，CI 一般不应依赖 go.work 来测试模块被其他模块要求时的行为。此时可以明确关闭工作区：

# 用单模块语义构建 app，避免读取仓库中的 go.work。
GOWORK=off go test ./...

# 需要检查发布依赖时，应在 app 的 go.mod 中使用目标版本。
GOWORK=off go list -m all

如果确实要让 CI 使用本地模块，不要用个人机器上的绝对路径或临时生成目录。把目录布局、go.work、checkout 策略和运行目录当作一组契约管理。若只需要临时替换一个依赖，也要让替换路径在 CI 中可获得，并在测试结束后明确恢复，避免把本地联调配置误当成发布配置。

把路径和回归检查固定在流水线

建议把失败提前到构建前，而不是等编译器报一个模糊的 import 错误。下面的检查既能发现缺文件，也能记录 Go 最终采用的工作区：

set -eu

# 这些变量描述本 job 的固定目录，不依赖开发者的本地布局。
repo_root="$(git rev-parse --show-toplevel)"
cd "$repo_root"

# 先检查工作区引用的每个模块根目录。
test -f go.work
test -f app/go.mod
test -f shared/go.mod

# 记录解析结果，再运行真正的模块测试。
printf 'GOWORK=%s\n' "$(go env GOWORK)"
printf 'GOMOD=%s\n' "$(go env GOMOD)"
go test ./app/...

这里的检查只适用于“仓库内多模块联调”这条流水线。如果目标是消费者兼容性，改成进入 app 后执行 GOWORK=off go test ./...，并让 app/go.mod 记录可获得的依赖版本。两条流水线都可以存在，但名称和门禁要写清楚，否则修复路径问题时很容易把测试目标也改掉。

排障可以按四项速查：文件看 go.work 和每个 go.mod 是否被检出；路径看 use 是否从工作区文件位置正确指向模块根；状态看 GOWORK、GOMOD 和 go list -m all；语义确认当前 job 是联调还是消费者测试。四项对齐后，CI 找不到目录通常就不再是 Go 命令本身的谜题，而是 checkout 契约不一致。

常见问题

go work use ./shared 会把 shared 模块复制到 app 吗？

不会。它把包含 go.mod 的本地目录加入工作区，构建时让这些模块作为主模块参与解析；目录仍必须存在于当前文件系统中。

本地能用，CI 一定要提交 go.work 吗？

不一定。内部多模块联调需要它时可以提交并完整检出；模拟外部消费者时更适合关闭工作区，使用目标模块自己的 go.mod。