Go workspace 中 replace 和 use 同时存在时谁优先

先给结论：use 和 replace 不是同一种指令，不能按“谁写在后面谁优先”来判断。use 把某个目录里的模块加入 workspace，并把它当作主模块参与构建；replace 改写的是某个依赖模块版本或路径的来源。对一个已经被 use 纳入 workspace 的主模块，go.work 不能再用“所有版本”的通配 replace 去替换它，否则会直接报 workspace 主模块冲突。

如果目标是替换 workspace 中某个外部依赖，go.work 的同模块替换会覆盖 workspace 模块各自 go.mod 里的替换；如果目标本身就是 workspace 主模块，应优先检查 use 路径，而不是继续叠加 replace。

官方参考：https://go.dev/ref/mod#workspaces

先区分 use 选择主模块和 replace 改写依赖

排查这类问题时，先不要把两个关键字放在同一条“优先级”线上。它们处理的是两个不同问题：

所以，回答“谁优先”前必须先问：冲突的是 workspace 主模块本身，还是一个仍然作为依赖解析的模块？前者通常是 use 路径或 workspace 范围问题；后者才是 replace 覆盖关系。

用三种配置看清谁会生效

假设目录里有 app、lib 和一份本地修复副本 fork-lib：

workspace/
├── go.work
├── app/go.mod       # module example.com/app
├── lib/go.mod       # module example.com/lib
└── fork-lib/go.mod  # module example.com/lib

第一种配置把 app 和 lib 都加入 workspace：

go 1.23

use (
    ./app
    ./lib
)

此时 example.com/lib 是 workspace 主模块。app 导入它时，构建使用的是 ./lib 这份主模块源码，而不是先去模块缓存寻找一个版本。这里起作用的是 use 带来的主模块集合，不是一个隐含的 replace。

第二种配置不把 lib 加入 workspace，只在 go.work 里替换一个外部依赖：

go 1.23

use ./app

// 只把依赖图中的 lib 重定向到本地修复副本。
replace example.com/lib v1.4.0 => ./fork-lib

这里 example.com/lib 仍是依赖模块，replace 才是决定源码位置的指令。即使 app/go.mod 对同一模块写了另一个替换，workspace 文件里的替换也会覆盖 workspace 上下文中同模块的 go.mod 替换。

第三种配置是 lib 已经在 use 中，同时又写：

go 1.23

use (
    ./app
    ./lib
)

// 这里试图把 workspace 主模块 example.com/lib 的所有版本替换掉。
replace example.com/lib => ./fork-lib

这不是“replace 成功覆盖 use”，而是无效组合。Go 会把 example.com/lib 识别为 workspace 主模块，同时看到一条针对它所有版本的 workspace 替换，并报错要求移除替换或改成带版本的替换。修复时不要只调换两行的顺序，因为文件顺序不会改变这两个指令的语义。

为什么通配 replace 会与 workspace 主模块冲突

模块作为 workspace 主模块时，它没有一个需要从依赖图中选择的版本。use ./lib 已经告诉 Go：这个模块的源代码就在工作区，构建要把它作为主模块加载。通配形式 replace example.com/lib => ... 却表达了“无论选择哪个版本，都把这个模块改到另一处”，两种声明的对象不同，不能把它们当成普通的覆盖关系。

这也是为什么下面的报错方向是“移除 workspace 中的替换，或指定替换版本”，而不是“后面的指令覆盖前面的指令”。通常有三种真实意图，对应三种写法：

1. 开发 workspace 里的模块：保留 use ./lib，删除针对同一模块的通配 replace。
2. 测试外部模块的修复副本：不要把原模块目录加入 use，改为在 go.work 里用带版本的 replace 指向副本。
3. 只替换某个明确版本：写出旧模块版本，并确认这条替换确实匹配依赖图中的版本；不要用省略版本的写法扩大范围。

如果多个 workspace 主模块的 go.mod 又分别声明了彼此冲突的替换，Go 也不会静默挑一个，而会报告 conflicting replacements。此时应把团队想要的替换集中写进 go.work，或者移除各模块里的临时替换。

用 go env 和 go list 定位实际来源

遇到“我明明改了 replace，构建为什么还在用旧代码”时，先确认命令是否真的进入了目标 workspace。GOWORK 被设为 off 时，即使父目录存在 go.work，当前命令也会回到单模块模式。

# 先确认当前目录实际使用哪一份 go.work；空值表示没有进入 workspace。
go env GOWORK

# 查看模块路径、版本和解析到的目录，重点观察 lib 的 Dir。
go list -m -f '{{.Path}} {{.Version}} => {{.Dir}}' all

# 临时关闭 workspace，比较单模块上下文下的模块来源。
GOWORK=off go list -m -f '{{.Path}} {{.Version}} => {{.Dir}}' all

如果第一条命令返回一份并非预期的 go.work，先检查当前目录和父目录；如果返回 off，先检查环境变量或命令包装脚本。第二条命令可以直接看模块目录，避免只凭缓存时间或编辑器提示猜测。第三条命令用于对比，不是永久修复配置。

还可以用 go env GOMOD 查看当前命令关联的模块文件。注意，go mod tidy、go mod edit 等命令有自己的单模块行为，不要把某一个命令的结果直接推断成所有 Go 命令都会忽略 workspace。

开发、CI 和发布分别怎么修

本地联调：用 use 表达正在一起开发的模块

多个模块需要同时改动时，推荐让 go.work 只表达本地联调范围：

# 在 workspace 根目录创建并加入两个本地模块。
go work init ./app ./lib

# 后续新增模块时只扩展主模块集合，不为同一模块叠加通配 replace。
go work use ./tools

这样依赖关系清晰：这些目录是本地 workspace 主模块，其他没有加入的模块仍按依赖版本解析。提交代码前要特别检查团队是否约定提交 go.work；官方文档提醒，提交它可能让 CI 误选本地组合。

临时修复依赖：用 go.work replace，但不要 use 原模块

如果你要验证一个外部依赖的补丁，目标是“保留应用主模块，替换依赖来源”，就把修复副本作为替换目标，而不是把同一个模块路径的原目录和副本同时加入 use：

go 1.23

use ./app

// 只替换明确版本，避免把 workspace 主模块和依赖替换混在一起。
replace example.com/lib v1.4.0 => ./fork-lib

验证补丁结束后，删掉这条临时替换或把它放在明确的本地开发文件中，避免 CI 和发布构建意外带上本地目录。

CI 与发布：用单模块语义检查真实依赖

如果仓库不是专门以多个模块一起发布，CI 通常应该显式决定是否启用 workspace。可以在关键任务中使用 GOWORK=off，让每个模块按它自己的 go.mod 和依赖版本构建；本地联调则保留开发者自己的 go.work。重点不是永远关闭 workspace，而是让环境选择可见、可重复。

最后用一张表回答“谁优先”

结论：先判断对象，再谈替换优先级

这道题最容易记错的地方，是把 use 和 replace 当成同一条覆盖链。更准确的规则是：use 决定哪些本地模块成为 workspace 主模块；对仍属于依赖图的模块，go.work replace 覆盖 workspace 模块中同模块的 go.mod replace；如果替换目标已经是 workspace 主模块，通配替换会变成错误配置。

排错时按“go env GOWORK → 主模块是否在 use → 依赖版本是否匹配 → go list -m 的实际目录”这个顺序检查，通常比反复调整 go.work 行顺序更快。

相关问题

go.work 的 replace 会覆盖 go.mod 的 replace 吗？

在 workspace 上下文中，对同一模块或模块版本，go.work 的替换优先于 workspace 模块里的替换；但如果目标是已纳入 workspace 的主模块，通配替换可能直接构成冲突，而不是成功覆盖。

use 和 replace 能不能同时写在同一份 go.work？

可以，只要它们作用于不同对象：use 加入本地开发模块，replace 替换另一个仍作为依赖解析的模块。不要把同一模块既当 workspace 主模块，又用通配 replace 指向另一份源码。

为什么我删了 replace，程序还是使用旧代码？

先确认当前命令是否使用了预期的 go.work，再用 go list -m -f '{{.Path}} => {{.Dir}}' all 看实际目录。还要检查是否存在父目录的 workspace、GOWORK=off，以及依赖版本是否根本没有匹配到你删除的那条替换。