Go 模块发现错误版本后怎样使用 retract

如果一个 Go 模块已经发布了错误版本，第一反应不应该是删除 tag 或覆盖同名版本。更稳妥的做法是：在模块的 go.mod 中增加 retract，再发布一个更高版本，让 Go 工具链在选择新依赖时避开问题版本。旧版本仍留在仓库和代理中，已经依赖它的项目才不会突然无法构建。

先把 retract 的边界说清楚

retract 是模块作者对未来依赖选择发出的信号：某个版本或一段版本区间不应再被新项目依赖。它不会从版本仓库、模块代理或已经生成的构建中抹掉版本，因此不能把它当作“撤销发布”。如果问题只影响一个 tag，就撤回单版本；如果一批版本都受影响，就用闭区间。

在 go.mod 中写入撤回声明

假设 v1.4.0 暴露了不兼容行为，模块维护者可以先在工作分支的 go.mod 写入：

module example.com/payments

go 1.23

retract v1.4.0 // 误发布了不兼容的默认超时行为

如果 v1.4.0 到 v1.4.3 都有同一个问题，可以写成：

retract (
    // 这些版本使用了错误的签名校验默认值
    [v1.4.0, v1.4.3]
)

注释不是语法必需项，却是给使用者看的排查线索。不要把 exclude 写进模块自身来代替它：exclude 是使用方模块的选择约束，而 retract 是被依赖模块作者发布的版本提示。

为什么还要发布一个更高版本

Go 命令会从模块的“最新可见版本”读取撤回信息。也就是说，单纯修改本地 go.mod 或重新指向已经发布的 v1.4.0，不会让公共模块消费者自动看到撤回。常见做法是把上面的声明提交并打一个更高版本，例如 v1.4.1：

# 先确认工作树中的撤回声明已经提交
git diff -- go.mod
git add go.mod
git commit -m "module: retract v1.4.0"

# 发布更高版本，让 @latest 能读到 retract
git tag v1.4.1
git push origin v1.4.1

如果不希望 v1.4.1 被正常业务依赖，可以让它只承载撤回信息，并同时撤回自身。关键不是版本号大小本身，而是它必须成为工具查询时能看到的最高版本。

用命令核对撤回是否生效

先把撤回版本也列出来，避免普通版本列表把它隐藏后造成误判：

# 包含已撤回版本，便于确认声明是否被读取
go list -m -retracted -versions example.com/payments

# 检查当前模块图中是否出现可用更新或撤回提示
go list -m -u all

# 按 latest 解析时，通常会跳过已撤回版本
go get example.com/payments@latest

验证时注意三个边界：已经固定写入 require example.com/payments v1.4.0 的项目不一定立刻失败；撤回不会替你修改业务代码；Go 1.15 及更低版本不支持依赖模块中的撤回声明，旧工具链需要单独评估。

常见问题

撤回后能不能删除 Git tag？

不建议。撤回的设计就是让旧版本仍可取得，从而保护已有构建；删除 tag 可能把问题变成不可复现的依赖故障。

retract 和 replace 有什么区别？

retract 是模块作者公开声明某版本不应被新选择；replace 是当前使用方在自己的模块图中改写来源或版本，影响范围不同。

为什么 go list -m -versions 看不到被撤回版本？

这是默认行为。加上 -retracted 才会把撤回版本显示出来，便于排查历史依赖。

实际发布时，保留旧版本、写清原因、打出携带声明的更高版本，再用带 -retracted 的查询核对，是一条更容易回滚和解释的处理路径。