本文目录导读：
- 场景一：代码已 push，但包尚未发布（最简单）
- 场景二：包已经发布到 npm（Node.js/JavaScript）
- 场景三：包已经发布到 PyPI（Python）
- 场景四：包已经发布到 RubyGems
- 场景五：包已经发布到 Maven Central（Java）
- 场景六：Docker 镜像
- 总结建议的操作流程
开源项目发布失败后，回滚（Rollback）的具体操作取决于你使用的包管理器（如 npm, PyPI, Maven, RubyGems 等）以及发布阶段（是代码已经推送了，但包还没发布？还是包已经发布到公共仓库了？）。
非常重要的核心原则：
绝大部分公共包管理器（如 npm, PyPI, RubyGems）不允许真正删除一个已发布的版本，因为一旦有人依赖了那个版本，删除会导致对方的构建失败（“依赖地狱”），通常只能 “撤回” (Yank) 或 “标记为不安全”。
以下是针对不同场景和主流工具的回滚方案：
代码已 push，但包尚未发布（最简单）
如果只是在 Git 上推送了错误的代码（例如合并了有问题的 PR）,回滚代码即可。
# 1. 将本地和远程分支回滚到上一个正确版本 git reset --hard <上一个正确版本的commit-hash> git push --force-with-lease origin <分支名>
注意：force push 会覆盖远程历史，如果有人在你的错误版本上做了开发，会很麻烦，沟通好再操作。
包已经发布到 npm（Node.js/JavaScript）
npm 不允许删除已发布的包（除非发布后 72 小时内且无人下载，但规则很严格），标准做法是 弃用 (Deprecate) 或 撤包 (Unpublish) 的替代方案。
使用 npm deprecate（最推荐）
这会在用户安装时显示警告，告诉用户不要用这个版本,同时保留历史记录。
npm deprecate <package-name>@<版本号> "此版本有严重bug，请回退到1.0.0" # npm deprecate my-library@2.1.0 "发布失败，回退至2.0.9"
使用 npm unpublish（仅限于 72 小时内发布且无依赖的包，不推荐）
风险极高，可能导致全球开发者项目无法构建，npm 官方非常不鼓励。
npm unpublish <package-name>@<版本号> --force
发布一个修补版（Roll-forward 重发）
这是大多数团队的“回滚”方式：修复 bug，增加补丁版本号（如从 2.1.0 变成 2.1.1）,然后重新发布。
# 修复代码 git commit -m "fix: 回滚发布失败问题" npm version patch npm publish
包已经发布到 PyPI（Python）
PyPI 同样不允许删除已发布的文件,但可以隐藏。
使用 YANK（推荐）
在 PyPI 项目页面，找到对应版本，点击 “Yank”，或者在命令行用 Twine 操作（比较麻烦），Yank 后，pip 安装该版本会报错（除非用户指定 --no-binary 但依赖解析会失败）。
重新发布新版本
如 1.0 坏了，就发布 1.1 修复版。
包已经发布到 RubyGems
RubyGems 允许 Yank 版本，但如果你 yank 的版本被其他人依赖,会破坏他们的环境。
gem yank <gem-name> -v <版本号>
包已经发布到 Maven Central（Java）
Maven Central 几乎不可能回滚，一旦发布，它会被镜像到全球,且政策极其严格。
- 唯一方案：发布一个新的修复版本。
- 补救：在 Release Notes 中明确标记该版本为“不可用”，或联系 Sonatype 支持（但通常也不会帮删除）。
Docker 镜像
Docker Hub 允许删除 tag 或整个仓库，但如果你使用了 latest 标签的自动构建,回滚就是重新打标签。
# 1. 获取之前的镜像 docker pull myapp:1.0.9 # 2. 重新打上 latest 标签 docker tag myapp:1.0.9 myapp:latest # 3. 推送覆盖 docker push myapp:latest # 4. 删除错误的tag docker push --all-tags # 或者单独删除远端tag
总结建议的操作流程
- 立即暂停发布：如果正在 CI/CD 流水线中,立刻中止。
- 评估包管理器规则：是 npm（只能废弃）、PyPI（可 yank）还是 Maven（不可逆）？
- 首选退路：紧急发布一个 hotfix 版本（
1.1替代有问题的1.0）,这最符合开源生态。 - 如果必须隐藏：使用该平台的 Yank 或 Deprecate 命令。
- 通知用户：在 CHANGELOG、Readme、Issues 中告知用户：“版本 X.X.X 有严重问题，请使用 X.X.X-1 或等我们发布 X.X.X+1”。
禁止操作：不要在无人告知的情况下直接 force push 改写 Git 历史（如果包已发布），版本号是开源项目的契约,破坏契约会失去信任。
