多模块联调时 replace 与 go.work 的职责有什么区别

replace 与 go.work 都能让 Go 在本地使用另一个模块目录，但职责并不相同：go.mod 里的 replace 是当前主模块的依赖替换规则，go.work 的 use 是把多个本地模块一起加入主模块集合。多模块共同迭代优先用 go.work use；只想让一个应用临时换用某个分支或本地副本时，才在该应用的 go.mod 使用 replace。

官方文档：https://go.dev/ref/mod#go-mod-file-replace

replace 与 go.work 改变的是不同边界

看一个典型场景：app 依赖 example.com/lib，团队同时修改两个模块。app 的正式模块契约仍应包含一个可发布版本：

module example.com/app

go 1.22

// 正式依赖版本，供脱离本地联调环境后的解析使用
require example.com/lib v0.1.0

如果在 app/go.mod 追加本地替换，含义是“当 app 作为主模块时，把这个依赖版本的内容改从 ../lib 读取”：

module example.com/app

go 1.22

require example.com/lib v0.1.0

// 仅当前主模块联调时把 lib 内容替换为本地目录
replace example.com/lib v0.1.0 => ../lib

而 go.work 不修改 app/go.mod 的替换规则。它把 app 和 lib 都声明为当前工作区的主模块，Go 命令会直接使用工作区中的本地模块：

go 1.22

use (
    ./app // 应用模块加入工作区主模块集合
    ./lib // 共享库模块加入同一集合
)

核心区别表

场景一：两个本地模块共同开发，用 go.work use

如果 app 和 lib 都在同一仓库，开发者经常同时修改两边，使用 workspace 更自然。它不要求把 replace ../lib 重复写进 app、worker、gateway 等每个消费者的 go.mod。

# 在两个模块的共同父目录创建工作区
go work init ./app ./lib

# 确认 Go 命令当前使用的工作区文件
go env GOWORK

# 查看 use 列表，确认 app 与 lib 都是工作区主模块
go work edit -json

此时 app 仍保留对 lib 正式版本的 require。本地构建使用工作区里的 lib，关闭工作区后则回到 require 指定的可获取版本。开发配置与发布契约因此保持分离。

场景二：只有一个主模块需要临时换依赖，用 go.mod replace

如果只维护 app，希望临时验证一个依赖 fork、未发布修复或本地目录，replace 更精确。它可以替换特定版本：

require example.com/lib v0.1.0

// 只替换 v0.1.0，其他版本仍按正常来源解析
replace example.com/lib v0.1.0 => ../lib-fix

也可以省略左侧版本，替换该模块的所有版本：

require example.com/lib v0.1.0

// 通配替换该模块的所有版本，范围更大，使用时要谨慎
replace example.com/lib => ../lib-fix

右侧是本地目录时，该目录必须是替代模块根目录，并包含 go.mod；其中的 module 路径应与被替换路径匹配。更重要的是，replace 单独存在没有效果：模块图中还要有对应的 require。

场景三：多个主模块的 replace 冲突，用 go.work replace 统一

workspace 模式下，所有主模块的 go.mod 都会参与。如果 app 与 worker 对同一模块写了冲突的 replace，Go 会拒绝含糊的替换。此时应删除重复规则，或在 go.work 中给出唯一的工作区级覆盖：

go 1.22

use (
    ./app    // 第一个主模块
    ./worker // 第二个主模块
)

// 工作区统一把指定版本指向同一个本地修复目录
replace example.com/lib v0.1.0 => ./lib-fix

Go 官方规则是：go.work 中的替换可以覆盖工作区模块 go.mod 里的同模块、同版本替换；go.work 中不带左侧版本的通配替换，还能覆盖 go.mod 中针对具体版本的替换。这个能力适合统一本地实验，不应被误解为发布后的全局规则。

怎样确认现在到底是谁在生效

联调出现“代码不是我刚改的”“CI 与本地版本不同”时，按下面的信号快速判断：

# 非空时说明当前命令正在使用某个 go.work
go env GOWORK

# 查看工作区的 use 与 replace，定位工作区级覆盖
go work edit -json

# 查看 lib 的最终模块信息；Replace 字段会显示实际替代来源
go list -m -json example.com/lib

# 关闭工作区后再次查看，比较单模块解析结果
GOWORK=off go list -m -json example.com/lib

若开关 workspace 前后 Replace 或模块目录发生变化，说明差异来自 go.work。若关闭 workspace 后仍指向本地目录，则继续检查当前主模块的 go.mod replace。

按场景选择，而不是互相替代

发布前的回滚与验证手册

临时实验结束后，把本地替换撤掉，再在单模块模式下整理和测试：

# 从 app/go.mod 删除针对 lib 的临时替换
cd app
go mod edit -dropreplace=example.com/lib@v0.1.0

# 关闭工作区整理模块文件，避免 go.work 遮住缺失依赖
GOWORK=off go mod tidy

# 以外部消费者视角运行测试
GOWORK=off go test ./...

若替换写在 go.work，则在工作区根目录撤销：

# 删除工作区中特定版本的 replace 覆盖
go work edit -dropreplace=example.com/lib@v0.1.0

# 不再共同开发 lib 时，从主模块集合移除它
go work edit -dropuse=./lib

# 格式化剩余的本地工作区配置
go work edit -fmt

回滚之后，app/go.mod 里应保留真实的 require example.com/lib v0.1.0，并且这个版本能从版本库或配置好的模块代理获取。若只能在 ../lib 存在时构建，发布契约仍不完整。

CI 需要同时防两种“本地成功”

第一种是 go.work 把本地 lib 加为主模块；第二种是 app/go.mod 仍留着相对路径 replace。两者都可能让开发机成功、外部消费者失败。CI 可以先关闭工作区，再禁止 go.mod 在发布分支保留本地路径替换。

steps:
  - name: Test module without workspace
    working-directory: app
    env:
      # 强制只读取 app/go.mod，不使用父目录 go.work
      GOWORK: "off"
    run: go test ./...

  - name: Show effective dependency source
    working-directory: app
    env:
      # 输出单模块视角的最终模块来源，便于失败时定位
      GOWORK: "off"
    run: go list -m -json example.com/lib

常见误区

写了 replace 为什么模块仍然不存在？

replace 不会把模块加入模块图。还需要 require 指向被替换的模块版本，或者由其他依赖的 go.mod 引入该版本；左侧版本未被要求时，这条 replace 不生效。

依赖模块自己的 replace 会传给 app 吗？

不会。replace 只在主模块的 go.mod 中生效，依赖模块 go.mod 里的 replace 会被忽略。workspace 有多个主模块时，各主模块规则都可能参与，但冲突替换必须消除或由 go.work 覆盖。

用了 go.work 后还要保留 require 吗？

要。go.work 负责本地多模块联调，外部消费者只看到发布模块的 go.mod。没有正式 require 与可获取版本，关闭工作区后仍会失败。

能把所有 replace 都搬到 go.work 吗？

只适合本地或工作区级实验。若 replace 表达的是模块对某个 fork 的正式、长期依赖，应改成真实模块路径与版本；若只是多个本地模块共同开发，优先用 use，而不是把每个本地模块都写成 replace。

一句话收尾：replace 回答“这个依赖版本的内容从哪里来”，go.work use 回答“哪些本地模块一起作为主模块开发”。选择时先看边界，再看场景；发布时关闭 workspace，用正式 require 和单模块测试证明配置没有只在本机成立。