retract 是 go 1.16+ 引入的模块版本撤回机制，由模块作者在 go.mod 中声明，用于标记已发布但存在严重问题的版本为“应被忽略”，仅影响下游新引入或更新行为，不删除 tag、不回滚本地依赖。
什么是 retract 声明
retract 声明不是回滚本地依赖，而是由模块作者在 go.mod 中主动标记某个已发布版本为“应被忽略”。它解决的是「错误版本已推送到公共仓库、无法撤回 tag、但希望用户不再选用」的问题。Go 1.16+ 才支持该机制，且只对下游用户的 go get 和 go mod tidy 生效——它不改变你本地的 go.mod，也不影响已缓存的版本。
如何添加 retract 声明
模块维护者需在自己项目的 go.mod 文件末尾追加 retract 行，格式为 retract v1.2.3 或 retract [v1.0.0, v1.5.0)（支持区间）。注意：
- 必须用
git tag推送新版本（哪怕只是go.mod变更），否则下游无法感知 - retract 不会删除远程 tag，也不影响已有构建；它仅修改模块的“可用版本列表”
- 区间写法中右括号必须是
)，不能写成]；闭区间如[v1.2.0, v1.2.3]是非法语法 - 执行
go mod tidy后，本地不会自动降级已引入的版本——只有新拉取或更新时才会避开被 retract 的版本
retract 对下游用户的影响
当你作为使用者运行 go get example.com/pkg@latest 或 go mod tidy 时，Go 会跳过所有被 retract 的版本。但要注意几个关键边界：
- 如果项目里已显式 require
v1.2.3（且该版本被 retract），go build仍能通过——retract 不破坏现有构建，只阻止新引入 -
go list -m -versions example.com/pkg会显示被 retract 的版本，但标注(retracted) - 若依赖树中某间接依赖强制要求被 retract 的版本，
go mod tidy会报错：「requirement of retracted version」，此时必须升级上游模块或手动指定兼容版本 - 私有模块启用 retract 需确保 GOPROXY 能正确代理该模块元信息，否则下游无法读取 retract 声明
retract vs 手动修改 go.mod 的本质区别
很多人想靠删掉 go.mod 里的某行 require 来“撤回”，这是无效的。retract 是模块作者发布的**全局策略声明**，而手动改 go.mod 只是本地快照变更。真正容易被忽略的是：retract 不解决本地缓存污染问题——如果之前下载过被 retract 的版本，它仍留在 $GOPATH/pkg/mod/cache 里，可能干扰调试。遇到奇怪的 invalid version 或校验失败，先试 go clean -modcache 再重试 go mod tidy。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
