Go module retract 发布后怎么阻止用户选到坏版本

如果 Go 模块的某个版本已经发布，却发现了会影响使用者的严重问题，不要删除 tag，也不要只在仓库首页写说明。正确做法是在 go.mod 中加入 retract，然后发布一个更高版本承载这条声明。这样后续 go get、go mod tidy 和 @latest 选择会避开坏版本，已经锁定旧版本的构建仍能继续工作。

一句话记住：retract 是“阻止未来自动选中”，不是“抹掉已经存在的版本”。撤回信息必须出现在一个更高、且能被解析为 @latest 的版本中。

先分清 retract 和删除版本

retract 适合“版本已经公开，但不应该再成为新项目的默认选择”的场景，例如误发布、严重 bug 或不应继续传播的实现。它不会把版本从 Git 标签或 module proxy 中抹掉；依赖方如果已经明确写着这个版本，构建仍应尽量保持可用。

这也是它和删除 tag 的区别：删除会让旧构建、缓存或审计记录变得不可预测，而撤回只改变之后的版本选择规则。Go 1.16 起支持该指令，Go 1.15 及更早版本在主模块中会报错或忽略依赖模块里的撤回信息。

在 go.mod 里声明要撤回的版本

单个坏版本写一个版本号，连续版本写闭区间。原因注释不是语法强制项，但建议保留，后续用户执行更新检查时可以看到判断依据。

module example.com/payments

go 1.23

retract (
    // v1.4.2 误把超时重试打开，可能造成重复扣款。
    v1.4.2

    // v1.3.0 到 v1.4.1 共用同一处错误的签名校验逻辑。
    [v1.3.0, v1.4.1]
)

区间两端都包含在内。不要为了“保险”随意扩大范围；如果只有一个版本有问题，就只撤回一个版本，否则会把本来可用的版本也从自动选择中排除。

发布更高版本，让 @latest 能读到撤回信息

只修改本地 go.mod 不会影响别人。需要提交这次修改并创建一个更高版本，例如 v1.4.3，让模块代理和 Go 命令能够从最新版本的 go.mod 加载撤回列表。

# 提交包含 retract 的 go.mod，并创建承载声明的新版本
git add go.mod
git commit -m "retract broken payment versions"
git tag v1.4.3
git push origin main --tags

# 查看 Go 命令按 @latest 读取到的模块元数据
go list -m -retracted example.com/payments@latest

这里的 v1.4.3 只是示例，实际版本必须按你的发布顺序递增。如果承载撤回信息的最高版本本身也有问题，可以同时撤回它；这时 @latest 会在排除撤回版本后回退到更低的可用版本。

发布后怎么确认坏版本不会再被自动选中

检查时不要只看一个命令。普通列表用于确认用户平时看到的版本，-retracted 用于故意把撤回版本也列出来，-u 用于观察当前依赖是否已经处在撤回版本。

如果项目已经固定到 v1.4.2，检查结果出现 (retracted) 并不表示构建立刻失败，而是提醒你主动升级或回退。可以先确认修复版本，再执行 go get example.com/payments@v1.4.3，最后重新运行项目测试。

常见问题

retract 能阻止用户手工安装坏版本吗？

不能完全阻止。它主要影响自动版本选择；用户明确指定被撤回版本时，工具仍可能加载它，并给出撤回提示。需要同时修复文档、发布说明或仓库流程。

撤回后要不要删除 Git tag？

通常不要。保留版本能让旧构建、缓存和源码追溯继续成立，撤回声明负责告诉后续选择逻辑避开它。

retract 和 exclude 有什么区别？

retract 是模块作者声明自己的版本不应再被依赖；exclude 是主模块对依赖图中的某个版本做本地排除，不能替代作者向所有使用者发布撤回信息。