Go modules 怎样用 retract 标记不可用版本

如果一个 Go 模块版本已经发布，但发现了严重缺陷、误发布或不应该继续被新项目选中，可以使用 retract 标记它。撤回不会把版本从仓库或模块代理上删除，已经依赖它的构建也不会因为撤回而自动失效；它的作用是让后续的版本查询和升级不要再把这个版本当成正常候选。

官方地址：https://go.dev/ref/mod

最稳妥的做法是：在新的、更高版本中加入 retract，写清原因并重新发布；然后用 go list -m 分别检查默认列表、包含撤回版本的列表和更新提示。不要用删除 tag 或 replace 代替撤回。

一、先判断 retract 解决的是什么问题

retract 面向的是“版本仍然存在，但不应继续作为依赖选择”的场景，例如某个 tag 提前发布、包含严重 bug，或者发布内容与预期不符。它和删除版本的思路不同：官方文档要求被撤回的版本继续留在版本控制仓库和模块代理上，这样已经依赖该版本的项目仍然可以复现构建。

二、在 go.mod 中写单个版本

单个版本直接写在 retract 后面，并建议附上原因注释。下面的例子表示 v1.4.0 已发布，但不应继续被新的依赖解析选中。

module example.com/payment

go 1.23.0

// v1.4.0 错误地发布了不完整的支付回调处理。
retract v1.4.0

这条声明本身只是模块元数据。要让其他项目读到它，还需要把包含该声明的 go.mod 发布为一个更高版本，例如 v1.4.1。只在本地编辑 go.mod，不会改变已经发布到代理上的版本集合。

三、需要连续撤回时写版本区间

如果一段连续版本都不应被选中，可以用闭区间表示下界和上界。区间两端都包含在撤回范围内；单个版本也可以看作上下界相同的区间。

module example.com/payment

go 1.23.0

retract (
    // 这些版本都缺少同一项关键的回调校验。
    [v1.4.0, v1.4.3]
)

不要用一个过宽的区间来掩盖尚未确认的问题。撤回范围应该能对应到明确的发布记录，原因注释也应该让维护者知道为什么从下界撤回到上界。

四、发布一个更高版本承载撤回信息

撤回信息由新版本携带。实际流程可以是：先在模块仓库修改 go.mod，再提交并打一个高于问题版本的 tag，最后让模块代理能够获取这个新版本。

# 先确认 go.mod 中已经写入撤回范围
git diff -- go.mod

# 提交撤回声明，提交信息说明影响范围
git add go.mod
git commit -m "module: retract broken releases"

# 发布高于问题版本的承载版本
git tag v1.4.4
git push origin main --tags

这里的关键不是 tag 名字本身，而是 @latest 能解析到包含撤回声明的版本。Go 命令会从该版本的 go.mod 读取撤回信息，再把它用于后续版本选择。

五、用 go list 区分默认列表和撤回列表

默认查看版本时，撤回版本会被隐藏；排查发布记录时可以显式加上 -retracted。这两个命令的差别很适合放进发布后的检查脚本中。

# 默认只看可作为正常候选的版本，撤回版本会被隐藏
go list -m -versions example.com/payment

# 排查历史发布时，把撤回版本也显示出来
go list -m -retracted -versions example.com/payment

# 查看当前依赖是否有更新，并关注 retracted 标记
go list -m -u all

如果需要确认某个特定版本是否仍在历史列表中，可以使用 -retracted 查询；如果目标是判断消费者会不会自动升级到它，则应观察不带该参数的版本选择。已经依赖撤回版本的项目通常仍能继续构建，但在检查更新或执行相关升级命令时会得到撤回提示。

六、两个容易忽略的边界

1. 承载版本也可以撤回自己

包含撤回声明的最高版本也可能因为新的问题被撤回。如果最高 release 或 pre-release 自己被撤回，@latest 在排除撤回版本后会解析到更低的版本。因此，发布流程需要确保撤回声明最终落在一个仍然可作为信息来源的更高版本上。

2. Go 1.15 及更低版本不支持同样的行为

retract 从 Go 1.16 开始加入。Go 1.15 及更低版本在主模块的 go.mod 中遇到该指令会报错；作为依赖读取时，也不会按新版本工具链那样应用撤回信息。如果项目仍需兼容旧工具链，要把这条限制写进发布说明，而不是以为所有消费者都会自动收到同样的提示。

发布前清单

1. 确认撤回的是已经发布的具体版本或连续区间，而不是一个仍在开发的本地版本。
2. 为每条撤回声明写清原因，避免只留下无法解释的版本号。
3. 发布一个高于问题版本、且能被 @latest 找到的承载版本。
4. 分别运行普通版本列表、-retracted 版本列表和 go list -m -u。
5. 在变更日志中说明已有构建继续可用，以及旧 Go 工具链的限制。

常见问题

撤回后，使用旧版本的项目会立刻构建失败吗？

不会。撤回主要影响后续版本选择和更新提示，已经依赖该版本的构建通常仍可继续；前提是仓库和模块代理仍保留该版本内容。

可以直接删除有问题的 tag 吗？

不建议把删除当成撤回。删除会让依赖旧版本的项目难以重新获取完全相同的源码，无法达到“保留构建、阻止新选择”的目标。

为什么我写了 retract，但 go get 仍然看到旧版本？

检查撤回声明是否已经发布到更高版本，并确认查询使用的模块路径和代理能够读取该版本。还可以用 go list -m -retracted -versions 区分“版本存在”与“版本可作为默认候选”这两个问题。

把 retract 当成模块发布历史的一部分，重点放在可追溯的原因、明确的版本范围和可验证的承载版本上，就能在不破坏旧构建的前提下纠正错误发布。