第48章 Cargo Add：向 Rust 项目添加依赖
名称
cargo-add — 向 Cargo.toml 清单文件添加依赖
概要
cargo add [选项] crate…cargo add [选项] --path pathcargo add [选项] --git url [crate…]
描述
该命令用于添加或修改依赖。
可以通过以下方式指定依赖来源：
- crate
@version：从 registry 获取，版本约束为 “version” --pathpath：从指定的 path 获取--giturl：从 url 处的 Git 仓库拉取
若未指定来源，命令会尝试自动选择最佳来源，包括：
- 其他表（如
dev-dependencies）中已存在的依赖 - Workspace 成员
- Registry 中的最新发布版本
添加已存在的包时，现有条目会根据指定的标志进行更新。
调用成功后，输出结果中会列出指定依赖已启用（+）和已禁用（-）的 features。
选项
来源选项
--giturl--branchbranch-
从 Git 添加时使用的分支。
--tagtag-
从 Git 添加时使用的标签。
--revsha-
从 Git 添加时使用的特定 commit。
--pathpath-
要添加的本地 crate 的文件系统路径。
--basebase-
添加本地 crate 时使用的路径基准。
--registryregistry-
要使用的 Registry 名称。Registry 名称定义在 Cargo 配置文件中。若未指定，则使用默认 Registry，该默认值由配置键
registry.default决定，其默认值为crates-io。
章节选项
--dev-
作为开发依赖添加。
--build-
作为构建依赖添加。
--targettarget-
作为特定目标平台的依赖添加。
为避免意外的 Shell 展开，建议给每个目标加上引号，例如：
--target 'cfg(unix)'。
依赖选项
--dry-run-
仅模拟执行，不实际写入清单文件
--renamename-
重命名该依赖。
--optional-
将该依赖标记为可选（optional）。
--no-optional-
将该依赖标记为必需（required）。
--public-
将该依赖标记为公开。
该依赖可以在库的公开 API 中被引用。
--no-public-
将该依赖标记为私有。
虽然可以在实现中使用该 crate，但不能在公开 API 中引用它。
--no-default-features--default-features-Ffeatures--featuresfeatures-
使用空格或逗号分隔的列表来指定要启用的功能。在添加多个 crate 时，可以使用
package-name/feature-name语法为特定 crate 启用功能。此参数可以多次指定，所有指定的功能都会被启用。
显示选项
-v--verbose-
使用详细输出。指定两次可产生“非常详细”的输出，包含依赖项警告和构建脚本输出等额外信息。也可以通过
term.verbose配置项 指定。 -q--quiet-
不打印 Cargo 日志信息。也可以通过
term.quiet配置项 指定。 --colorwhen-
控制何时使用彩色输出。有效值包括：
auto（默认）：自动检测终端是否支持彩色。always：始终显示彩色。never：从不显示彩色。
也可以通过
term.color配置项 指定。
清单选项
--manifest-pathpath-
Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录或其父目录中查找该文件。
-pspec--packagespec-
仅将依赖项添加至指定的包。
--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 文档。 --configKEY=VALUE 或 PATH-
覆盖 Cargo 的配置项。参数可以是
KEY=VALUE形式的 TOML 语法，也可以是一个额外配置文件的路径。此标志可以指定多次。更多信息请参阅命令行覆盖一节。 -CPATH-
在执行任何指定操作之前先切换当前工作目录。这会影响 Cargo 默认查找项目清单（
Cargo.toml）的位置，以及搜索.cargo/config.toml的目录等。此选项必须放在命令名之前，例如cargo -C path/to/my-project build。此选项仅在 nightly channel 上可用，并且需要启用
-Z unstable-options标志（参见 #10098）。 -h--help-
打印帮助信息。
-Zflag-
Cargo 的不稳定（仅 Nightly 可用）标志。运行
cargo -Z help查看详情。
环境变量
有关 Cargo 读取的环境变量的详细信息，请参阅参考文档。
退出状态
0：Cargo 成功。101：Cargo 执行失败。
示例
-
添加
regex作为依赖项cargo add regex -
添加
trybuild作为开发依赖项cargo add --dev trybuild -
添加旧版本的
nom作为依赖项cargo add nom@5 -
添加对使用
derive将数据结构序列化为 json 的支持cargo add serde serde_json -F serde/derive -
在
cfg(windows)下添加windows作为特定平台的依赖项cargo add windows --target 'cfg(windows)'
