Go workspace 模式为什么忽略 go.mod 里的本地 replace

Go workspace 模式并不会无条件忽略 go.mod 里的 replace。真正的规则是：工作区中的多个模块都会成为主模块，它们的 go.mod 会共同参与解析；如果 go.work 对同一模块或同一版本定义了 replace，工作区级配置优先。另一个高频原因是 replace 左侧限定了版本，但构建列表实际选中的版本不同。

先运行 go env GOWORK。只要输出了某个 go.work 路径，就应同时检查该文件、其中的 use 列表以及所有工作区主模块的 go.mod，不能只盯着当前目录的一个文件。

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

先确认命令到底处于哪种工作区

当 GOWORK 为空或没有显式设置时，Go 命令会从当前目录向父目录查找 go.work。这意味着你在子模块目录执行 go test，仍可能自动进入父目录定义的工作区。此时看到的依赖解析结果不再只是当前 go.mod 的单模块结果。

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

# 临时关闭工作区模式，比较同一模块在单模块模式下的解析结果。
GOWORK=off go list -m all

# 在当前工作区模式下查看最终构建列表，便于对照差异。
go list -m all

如果 GOWORK=off 后本地替换恢复，问题已经缩小到工作区配置；如果两种模式都没有生效，则继续检查版本匹配、模块路径和本地目录结构。

理解 go.work 为什么可以覆盖 go.mod

go.work 的核心用途是把多个本地模块同时设为主模块。每个主模块自己的 replace 可以参与工作区解析，但工作区级 replace 专门用于统一或覆盖这些配置。Go 官方规则明确说明：go.work 中针对同一模块或模块版本的替换，会覆盖工作区模块 go.mod 中的替换；工作区里的通配替换还可以覆盖 go.mod 的版本限定替换。

// go.work：工作区级替换对所有 use 模块生效。
go 1.23.0

use (
    ./app
    ./lib
)

// 该通配替换覆盖工作区模块里同一路径的版本限定 replace。
replace example.com/shared => ./shared-workspace

因此，如果 app/go.mod 里写的是 replace example.com/shared => ../shared-local，最终仍可能使用 ./shared-workspace。这不是 go.mod 被随机忽略，而是工作区选择了更高层级的统一替换。

多主模块会把隐藏冲突暴露出来

单独进入 app 或 lib 构建时，各自的 replace 没有冲突；把它们加入同一个 go.work 后，两个 go.mod 都成为主模块配置。如果它们把同一个模块版本替换到不同位置，Go 不会默默挑一个，而是要求删除冲突，或在 go.work 中写一个明确的覆盖。

这个设计避免同一条工作区命令因为当前所在子目录不同而得到不同依赖。工作区适合本地多模块联调，但统一性意味着不能保留彼此冲突的主模块替换。

版本限定不匹配也会造成“本地 replace 失效”

replace 左侧可以带版本，也可以不带版本。带版本时，只替换那个准确版本；不带版本时，替换该模块路径的所有版本。如果依赖图最终选择的是 v1.6.0，下面只针对 v1.5.0 的规则就不会命中。

// 只替换 v1.5.0；若构建列表选择 v1.6.0，此规则不会生效。
replace example.com/shared v1.5.0 => ../shared-local

// 不限定左侧版本，可用于本地联调该模块路径的任意选中版本。
replace example.com/shared => ../shared-local

还要注意，replace 本身不会把模块加入依赖图。目标模块必须由某个 require 或传递依赖引入，否则替换规则没有对象可替换。右侧是本地目录时，该目录必须是模块根目录并包含 go.mod，其中的 module 路径应与被替换模块匹配。

按使用场景选择修复位置

如果本地替换只服务当前模块的独立开发，把它留在该模块的 go.mod，需要独立验证时使用 GOWORK=off。如果替换服务整个多模块联调环境，则把统一规则写进 go.work，并删除各模块中互相冲突的替换。

# 检查工作区文件里是否已经存在同路径的覆盖规则。
go work edit -json

# 用工作区级通配替换统一所有主模块的本地依赖位置。
go work edit -replace=example.com/shared=./shared-workspace

# 再次查看最终模块映射；输出中的 Replace 字段可反映实际替换对象。
go list -m -json example.com/shared

团队仓库是否提交 go.work 要根据协作方式决定。若每个人的本地目录布局不同，提交带个人路径的替换会制造新的环境差异；若仓库本身就是固定的多模块工程，使用相对路径的工作区配置通常更容易复现。

最后用五项清单复查

• go env GOWORK 是否指向了意料之外的父目录文件。
• go.work 是否对同一模块或版本定义了更高优先级的 replace。
• 多个 use 模块的 go.mod 是否存在互相冲突的替换。
• replace 左侧版本是否与 go list -m all 的选中版本一致。
• 被替换模块是否真的进入依赖图，本地目录是否包含匹配模块路径的 go.mod。

相关问题

为什么在 IDE 中有效，命令行却无效？ 两边可能使用了不同工作目录、环境变量或 GOWORK。先分别确认实际使用的工作区文件。

go work sync 能修复 replace 优先级吗？ 不能。它把工作区构建列表中的版本同步回各模块，不会替你消除冲突或改写替换意图。

临时排查时可以删除 go.work 吗？ 不必。使用 GOWORK=off 就能临时切回单模块模式，便于对照。

所以，所谓“workspace 忽略 go.mod replace”，通常可以还原成一个明确的解析问题：命令采用了哪个 go.work、哪个层级定义了同路径替换、版本是否命中，以及目标模块是否真的在构建列表中。