Go go.mod exclude 和 retract 解决的问题有什么区别

如果你在维护业务项目，发现某个依赖版本不能再进入当前构建，通常要考虑 exclude；如果你是模块作者，已经发布的版本存在严重问题，需要提醒所有后续使用者不要自动升级到它，则应考虑 retract。两者都能避开“问题版本”，但一个修正消费方的模块图，一个修正发布版本的后续选择。

记忆方法：当前项目不想用某个版本，用 exclude；自己发布的版本不该再被新用户选中，用 retract。它们都不是 replace，也不能互相替代。

先按影响对象分清两条规则

最容易混淆的地方是：两个关键字都出现在 go.mod，但“谁来写”和“影响谁”完全不同。exclude 是消费方对自己的主模块负责。它不会替上游作者修改发布记录，也不会让其他项目自动避开同一版本。

retract 是发布方的版本声明。作者发现版本提前发布、包含严重缺陷或不适合作为后续依赖后，在新的、更高版本中加入撤回信息。版本仍保留在仓库和代理中，已经依赖它的构建不因为撤回就凭空消失，但后续版本查询会得到提醒或跳过它。

exclude 解决的是当前项目的依赖图问题

消费方可以在主模块中排除精确的模块版本：

module example.com/order

go 1.23

require example.com/payment v1.2.3

// 当前项目不接受这个已知有问题的版本。
exclude example.com/payment v1.2.3

这条规则只对主模块的 go.mod 生效，其他依赖模块里写的 exclude 不会替你的项目执行全局屏蔽。模块图计算时，被排除的版本会被移除；如果仍有依赖指向它，工具可能选择更高的可用版本，并在必要时更新 require。

因此，exclude 不是“把模块换成本地修正版”。需要换成 fork 或本地目录时看 replace；只是拒绝某一个版本时才用 exclude。改完后执行：

# 整理依赖声明，并让工具处理被排除版本的要求
go mod tidy

# 查看最终构建列表，确认问题版本没有被选中
go list -m all

retract 解决的是已发布版本的后续选择

假设模块作者误发布了 v1.4.0，之后在 v1.4.1 中补充：

module example.com/payment

go 1.23

// v1.4.0 提前发布，避免新项目继续自动采用。
retract v1.4.0

然后发布包含这条声明的更高版本。撤回信息可以写单个版本，也可以写闭区间，例如 retract [v1.4.0, v1.4.2]。它表达的是“这个模块版本不应再作为未来依赖选择”，不是删除 tag，也不是强制已经锁定该版本的项目马上改动。

检查撤回提示时，可以使用：

# 查看模块升级信息，其中可能包含撤回原因
go list -m -u example.com/payment

# 显式查看包含撤回信息的版本
go list -m -retracted example.com/payment@latest

用最小示例验证选择结果

遇到“这个版本有问题”时，先问两个问题：你是消费方还是发布方？希望改变当前构建，还是改变未来用户的版本选择？前者进入 exclude，后者进入 retract。

还有一个实际边界：如果问题版本来自上游，但你只是想让当前项目临时使用自己的 fork，exclude 仍然不够，因为它只负责拒绝版本；这时应评估 replace，并把替换范围、回滚方式和后续回到官方版本的计划写进项目记录。

常见问题

exclude 能写在依赖模块里影响所有下游吗？

不能。它只在主模块的 go.mod 中有这个作用，不能代替模块作者发布撤回声明。

retract 会删除已经发布的版本吗？

不会。撤回版本仍应可被仓库和代理访问，已有构建可以继续使用；它主要改变未来版本查询和升级时的选择与提示。

只是想换成 fork，应该用哪个？

用 replace，因为需求是改变模块内容来源；exclude 只表达“不选这个版本”。

把“当前项目的依赖图”和“模块作者的发布信誉”分开，基本就不会再把 exclude 与 retract 混用。前者服务一次构建的选择，后者服务后续用户的升级路径。