工作区里能编译但离开工作区失败，依赖缺口怎样找

这类问题通常不是“换个目录后 Go 坏了”，而是 go.work 把多个本地模块同时放进了构建列表，临时补足了单个 go.mod 没写完整的依赖。定位最快的方法是进入出问题的模块目录，用 GOWORK=off 重跑构建：若立即出现“找不到提供该包的模块”，缺口就在这个模块自己的依赖契约里。

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

为什么 go.work 会遮住 go.mod 的依赖缺口

工作区不是一个更大的 go.mod。它把 use 指向的多个磁盘目录都作为“主模块”参与同一次模块选择。假设仓库结构如下：

repo/
├── go.work        # 工作区同时加载 app 与 lib
├── app/
│   ├── go.mod     # 可能漏写对 example.com/lib 的 require
│   └── main.go
└── lib/
    ├── go.mod
    └── lib.go

go.work 只要同时包含两个模块，app 的源码就能直接解析本地 lib：

go 1.22

use (
    ./app // 应用模块
    ./lib // 本地联调的依赖模块
)

此时 app 的代码导入 example.com/lib，工作区构建可能成功，即使 app 自己的 go.mod 只有模块名而没有依赖声明：

module example.com/app

go 1.22

// 这里漏掉了 require example.com/lib v0.1.0

问题在 CI、独立 checkout、发布给其他仓库或关闭 workspace 后暴露，因为 Go 命令只能读取 app 的模块契约，再也看不到 use ./lib 提供的本地替代。官方教程也明确说明：工作区内能直接使用另一个主模块的代码；要让模块在工作区外解析，需要依赖模块已发布，并在消费者的 go.mod 中要求相应版本。

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

不要凭当前目录猜测。Go 命令会从当前目录逐级向父目录寻找 go.work；因此你在 repo/app 中执行命令，也可能仍受 repo/go.work 影响。先运行：

# 显示当前 Go 命令实际使用的 go.work；空输出表示未启用工作区模式
go env GOWORK

# 打印工作区声明，核对 use 是否把本地依赖模块纳入主模块集合
go work edit -json

若第一条输出了父目录中的 go.work 路径，就已经解释了“在仓库里成功”的环境差异。另一个常见线索是：编辑器、开发机命令和仓库根目录测试都成功，而只检出 app 子目录的流水线失败。

用 GOWORK=off 把单模块缺口直接暴露出来

进入真正需要独立发布或独立测试的模块根目录，再关闭工作区模式。GOWORK=off 是官方支持的单模块开关，它比临时移动或重命名 go.work 更明确，也不会修改仓库。

# 进入待验证模块，避免在仓库根目录误测别的包
cd app

# 关闭工作区，只按 app/go.mod 构建全部包
GOWORK=off go build ./...

# 查看单模块上下文中的构建列表，确认依赖版本是否可解析
GOWORK=off go list -m all

如果出现“no required module provides package example.com/lib”一类错误，说明 app 源码有导入，但 app/go.mod 没有提供可解析的模块要求。若错误变成“unknown revision”或下载失败，则依赖声明可能存在，但填写的版本没有发布、模块路径与标签不匹配，或私有模块访问配置不完整。

Windows PowerShell 可以用等价写法：

# 仅对当前 PowerShell 会话关闭工作区模式
$env:GOWORK = "off"

# 在 app 模块根目录执行独立构建
go build ./...

把本地联调关系变成可发布的模块契约

如果 lib 已经发布了 v0.1.0，app 的 go.mod 应明确要求它：

module example.com/app

go 1.22

require example.com/lib v0.1.0 // app 脱离工作区后仍能定位 lib

可以在关闭 workspace 的状态下让 Go 命令写入要求并整理校验和：

# 在 app 模块内记录可获取的 lib 版本
GOWORK=off go get example.com/lib@v0.1.0

# 按 app 的真实导入整理 go.mod 与 go.sum
GOWORK=off go mod tidy

# 最后仍以单模块上下文做构建和测试
GOWORK=off go test ./...

如果 lib 还没有发布版本，先确认目标：仅做同仓库本地联调时，go.work 很合适；要让 app 能被独立拉取和构建，就必须给 lib 建立可获取的版本（标签或合规的伪版本），再把版本写入 app/go.mod。临时在 app/go.mod 中加入本地 replace 可以帮助开发，但指向 ../lib 的相对路径不是可移植的发布方案。

go work sync 能做什么，不能替代什么

go work sync 会计算工作区的构建列表，并把与各工作区模块相关的依赖版本同步回相应 go.mod。它适合处理多个模块对同一外部依赖要求不一致的问题，例如工作区最终选中了更高版本，希望各模块的要求与之对齐。

# 把工作区构建列表中的相关版本同步回各 use 模块
go work sync

# 同步后仍关闭工作区检查 app 是否可以独立解析
cd app
GOWORK=off go test ./...

但它不能替你发布本地 lib，也不能把“磁盘上恰好存在的目录”变成外部消费者可下载的版本。判断是否修好，仍以 GOWORK=off 的单模块测试为准。

把缺口检查放进 CI，而不是等发布时发现

多模块仓库至少应有两层测试：仓库根目录可保留工作区集成测试；每个可发布模块还要关闭 workspace 独立测试。下面是与平台无关的 CI 片段：

strategy:
  matrix:
    # 每个可发布模块都在自己的 go.mod 边界内测试
    module: [app, lib]

steps:
  - name: Test module without go.work
    working-directory: ${{ matrix.module }}
    env:
      # 防止父目录 go.work 遮住依赖缺口
      GOWORK: "off"
    run: go test ./...

这样新增一个跨模块导入却忘记补 require 时，CI 会在合并前失败。官方模块参考通常不建议把个人开发用的 go.work 交给 CI，因为它可能改变依赖选择，让流水线测试的不是模块被外部依赖时的真实状态；如果仓库确实把多个模块作为一个不可拆分整体维护，也应同时保留单模块检查。

常见误区

把 go.work 一起提交，问题就算解决了吗？

不算。它可以统一仓库内的联调环境，却不能代替每个可发布模块的 go.mod。外部用户依赖的是模块路径和版本，不会自动得到你的本地 use 目录。

为什么 go mod tidy 没发现问题？

如果运行时仍启用了 workspace，Go 命令可以从工作区主模块解析导入，结果不等同于独立消费者。进入模块目录并显式设置 GOWORK=off 后再执行，才是在检查单模块契约。

可以永久使用 go.mod 的 replace ../lib 吗？

只适合受控的本地或单仓库布局。发布后，其他机器未必有同样相对目录；可复用模块应依赖可获取的版本。若项目从设计上永远作为一个仓库整体构建，也要把这个约束写进构建和 CI，而不是让它成为隐含前提。

归纳起来，排查顺序只有三件事：先用 go env GOWORK 找环境差异，再用 GOWORK=off 复现单模块构建，最后把本地可见性改造成 go.mod 中可获取、可版本化的依赖。工作区负责方便联调，模块文件负责对外承诺，两者职责分开后，这类“在我这里能编译”的问题就很容易定位。