09-cargo update

cargo-update(1) 更新依赖

  4 分钟阅读  

译文 · 基于 The Cargo Book

cargo-update(1)

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

名称

cargo-update — 按本地锁文件记录更新依赖

大纲

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 哈希或标签）。

虽然不推荐，但你可以指定已 yank 的包版本。 尽可能尝试其他未 yank 的 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

尝试仅更新工作空间中定义的包。其他包仅在锁文件中尚不存在时才会更新。 在你更改 Cargo.toml 中的版本号后更新 Cargo.lock 时，此选项很有用。

--dry-run

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

显示选项

-v
--verbose

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

-q
--quiet

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

--color when

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

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

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

清单选项

--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 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. 更新锁文件中的所有依赖：

    cargo update

  2. 仅更新特定依赖：

    cargo update foo bar

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

    cargo update foo --precise 1.2.3

参见

cargo(1), cargo-generate-lockfile(1)

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