06-cargo yank

cargo-yank(1) 撤回某个版本

  4 分钟阅读  

译文 · 基于 The Cargo Book

cargo-yank(1)

原文链接: https://doc.rust-lang.org/cargo/commands/cargo-yank.html

名称

cargo-yank — 从索引中移除已推送的 crate

大纲

cargo yank [options] crate@version
cargo yank [options] --version version [crate]

描述

yank 命令从服务器索引中移除先前发布的 crate 版本。此命令不删除任何数据， 该 crate 仍可通过注册表的下载链接下载。

对于没有预先存在锁文件的任何新项目或检出，Cargo 不会使用已 yank 的版本， 若你的 crate 不再有任何兼容版本，将生成错误。

此命令要求你通过 --token 选项或使用 cargo-login(1) 完成身份验证。

若未指定 crate 名称，将使用当前目录中的包名。

yank 如何工作

例如，foo crate 发布了版本 1.5.0，另一个 crate bar 声明了对版本 foo = "1.5" 的依赖。现在 foo 发布了新的但不兼容 SemVer 的版本 2.0.0， 并发现 1.5.0 有严重问题。若 yank 了 1.5.0，任何没有现有锁文件的新项目或检出 都将无法使用依赖 1.5 的 crate bar。

在这种情况下，foo 的维护者应在 yank 1.5.0 之前先发布 SemVer 兼容版本（如 1.5.1）， 以便 bar 以及所有依赖 bar 的项目继续工作。

再举一例，考虑已发布版本 1.5.0、1.5.1、1.5.2、2.0.0 与 3.0.0 的 crate bar。 下表标明在没有锁文件时，给定版本被 yank 后，Cargo 对不同 SemVer 需求可能使用的版本：

已 Yank 版本 / SemVer 需求bar = "1.5.0"bar = "=1.5.0"bar = "2.0.0"
1.5.0使用 1.5.1 或 1.5.2返回错误使用 2.0.0
1.5.1使用 1.5.0 或 1.5.2使用 1.5.0使用 2.0.0
2.0.0使用 1.5.0、1.5.1 或 1.5.2使用 1.5.0返回错误

何时 yank

仅应在例外情况下 yank crate，例如意外发布、无意的 SemVer 破坏，或严重损坏且无法使用的 crate。 对于安全漏洞，RustSec 通常是告知用户并鼓励升级的干扰更小的机制， 并可避免不论是否易受该漏洞影响都造成显著的下游中断。

常见工作流是在已发布 SemVer 兼容版本后再 yank 某个 crate， 以降低阻止依赖 crate 编译的可能性。

在处理已发布 crate 的版权、许可或个人数据问题时，仅 yank 可能不够。 在这种情况下，请联系你所用注册表的维护者。对于 crates.io，请参阅其政策并联系 help@crates.io。

若凭证已泄露，建议立即吊销。一旦 crate 已发布，就无法确定泄露的凭证是否已被复制。 yank 仅防止 Cargo 在默认解析依赖时选择此版本。现有锁文件或直接下载不受影响， 因此 yank 无法阻止泄露凭证的进一步传播。

选项

Yank 选项

--vers version
--version version

要 yank 或取消 yank 的版本。

--undo

撤销 yank，将版本放回索引。

--token token

身份验证时使用的 API 令牌。这会覆盖凭证文件中存储的令牌 （由 cargo-login(1) 创建）。

Cargo 配置环境变量可用于覆盖凭证文件中存储的令牌。 crates.io 的令牌可用 CARGO_REGISTRY_TOKEN 环境变量指定。 其他注册表的令牌可用形如 CARGO_REGISTRIES_NAME_TOKEN 的环境变量指定， 其中 NAME 为注册表名称的全大写形式。

--index index

要使用的注册表索引 URL。

--registry registry

要使用的注册表名称。注册表名称在 Cargo 配置 文件中定义。若未指定，则使用默认注册表， 由 registry.default 配置键定义，默认为 crates-io。

显示选项

-v
--verbose

使用详细输出。可指定两次以获得“非常详细”的输出，其中包含依赖警告与构建脚本输出等额外信息。 也可通过 term.verbose 配置值 指定。

-q
--quiet

不打印 cargo 日志消息。 也可通过 term.quiet 配置值 指定。

--color when

控制何时使用彩色输出。有效值：

  • auto（默认）：自动检测终端是否支持颜色。
  • always：始终显示颜色。
  • never：从不显示颜色。

也可通过 term.color 配置值 指定。

通用选项

+toolchain

若 Cargo 通过 rustup 安装，且传给 cargo 的第一个参数以 + 开头，则会被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。 关于工具链覆盖如何工作，见 rustup 文档。

--config KEY=VALUE or PATH

覆盖 Cargo 配置值。参数应为 TOML 语法的 KEY=VALUE， 或指向额外配置文件的路径。此标志可指定多次。 更多信息见 命令行覆盖一节。

-C PATH

在执行任何指定操作之前更改当前工作目录。这会影响 Cargo 默认查找项目清单（Cargo.toml）的位置，以及 用于发现 .cargo/config.toml 的目录搜索等。此选项必须 出现在命令名称之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly 通道 上可用，且 需要 -Z unstable-options 标志才能启用（见 #10098）。

-h
--help

打印帮助信息。

-Z flag

Cargo 的不稳定（仅 nightly）标志。运行 cargo -Z help 查看详情。

环境

关于 Cargo 读取的环境变量详情，见参考文档。

退出状态

  • 0：Cargo 成功。
  • 101：Cargo 未能完成。

示例

  1. 从索引中 yank 一个 crate：

    cargo yank foo@1.0.7

参见

cargo(1), cargo-login(1), cargo-publish(1)

最后修改 August 11, 2026: 更新 (70a5af133)