第56章 cargo update 命令详解

名称

cargo-update — 更新本地锁定文件（lock file）中记录的依赖项

用法

cargo update [options] spec

描述

此命令会将 Cargo.lock 文件中的依赖项更新到最新版本。如果 Cargo.lock 文件不存在，系统将使用最新可用版本创建该文件。

选项

更新选项

spec…

仅更新指定的软件包。此标志可以多次指定。SPEC 格式请参阅 cargo-pkgid(1)。

如果通过 spec 指定了软件包，则会对锁定文件执行保守更新。这意味着仅更新 SPEC 指定的依赖项。只有在无法通过更新依赖项来满足 SPEC 更新需求时，其传递依赖项才会被更新。其他所有依赖项将保持当前记录版本的锁定状态。

如果未指定 spec，则更新所有依赖项。

--recursive

与 spec 配合使用时，强制更新 spec 的依赖项。不能与 --precise 一起使用。

--precise precise

与 spec 配合使用时，允许指定将软件包设置为的特定版本号。如果软件包来自 git 仓库，此参数可以是 git 修订号（如 SHA 哈希值或标签）。

虽然不推荐，但您可以指定软件包的已撤销（yanked）版本。尽可能尝试其他非撤销的 SemVer 兼容版本，或向软件包维护者寻求帮助。

即使 Cargo.toml 中的版本要求不包含任何预发布标识符，也可以指定兼容的 pre-release（预发布）版本（仅限 nightly 版本）。

--breaking directory

将 spec 更新至最新的 SemVer 不兼容版本。

版本要求会被修改以允许此次更新。

此选项仅适用于满足以下所有条件的依赖项：

• 该包是某个工作区成员的依赖项
• 该依赖项未被重命名
• 存在 SemVer 不兼容的新版本
• 使用了“SemVer 操作符”（即默认的 ^）

此选项尚不稳定，仅在 nightly 渠道 可用，且需要启用 -Z unstable-options 标志。 更多信息请参考 https://github.com/rust-lang/cargo/issues/12425。

-w

--workspace

尝试仅更新工作区内定义的包。其他包只有在它们尚未存在于锁文件（lockfile）中时才会被更新。 在修改 Cargo.toml 中的版本号后，此选项对于更新 Cargo.lock 非常有用。

--dry-run

显示将被更新的内容，但不会实际写入锁文件。

显示选项

-v

--verbose

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

-q

--quiet

不打印 cargo 日志信息。也可通过 term.quiet 配置项 设置。

--color when

控制何时使用彩色输出。可选值：

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

也可通过 term.color 配置项 设置。

Manifest 选项

--manifest-path path

Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录及各级父目录中查找 Cargo.toml 文件。

--ignore-rust-version

忽略包中声明的 rust-version。

--locked

要求依赖及其版本与现有 Cargo.lock 文件生成时完全一致。出现以下任一情况时，Cargo 会报错退出：

• 锁文件不存在。
• Cargo 因依赖解析结果不同而需要修改锁文件。

适用于需要确定性构建的环境，比如 CI 流水线。

--offline

禁止 Cargo 访问网络。若未指定此标志，当 Cargo 需要访问网络但网络不可用时，它会报错并停止。若指定此标志，Cargo 会尝试在无网络的情况下继续执行。

注意，这可能导致与在线模式不同的依赖解析结果。Cargo 将限制使用本地已下载的 crate，即使本地索引副本显示存在更新的版本。请参考 cargo-fetch(1) 命令，在离线前预先下载依赖。

也可通过 net.offline 的 配置值 指定。

--frozen

等效于同时指定 --locked 和 --offline。

常用选项

+toolchain

如果 Cargo 是通过 rustup 安装的，且 cargo 的第一个参数以 + 开头，该参数将被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。关于工具链覆盖机制的更多信息，请参阅 rustup 文档。

--config KEY=VALUE 或 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. 更新锁文件中的所有依赖项：

   cargo update
   

2. 仅更新指定的依赖项：

   cargo update foo bar
   

3. 将指定依赖项设置为特定版本：

   cargo update foo --precise 1.2.3
   

另请参阅

cargo(1)、cargo-generate-lockfile(1)