《Cargo 参考手册》第二十一章：Cargo 包命令

cargo-init（在已存在的目录中创建新的 Cargo 包）

名称（NAME）

cargo-init --- 在已存在的目录中创建新的 Cargo 包

语法（SYNOPSIS）

cargo init [选项] [路径]

说明（DESCRIPTION）

该命令会在当前目录下创建一个新的 Cargo 清单文件（Cargo.toml）。如果想在指定目录创建，只需将路径作为参数传入即可。

如果目录中已经存在常规命名的 Rust 源文件，会直接使用这些文件。若不存在，会自动创建一个示例文件 src/main.rs；如果加上 --lib 参数，则会创建 src/lib.rs。

如果该目录尚未加入任何版本控制系统（VCS），会自动创建一个新的版本库（具体可查看下方 --vcs 选项说明）。

类似命令可参考 cargo-new (1)，它会在新目录中创建新的 Cargo 包。

选项（OPTIONS）

初始化选项（Init Options）

--bin：创建包含二进制目标文件（src/main.rs）的包，这是默认行为。
--lib：创建包含库目标文件（src/lib.rs）的包。
--edition edition：指定使用的 Rust 版本。默认是 2024，可选值包括 2015、2018、2021、2024。
--name name：设置包的名称，默认使用目录名。
--vcs vcs：为指定的版本控制系统（git、hg、pijul 或 fossil）初始化新仓库，也可指定为 none（不初始化任何版本控制）。若未指定，默认使用 git 或配置值 cargo-new.vcs；如果目录已在版本控制仓库内，则默认不初始化（none）。
--registry registry：在 Cargo.toml 的 publish 字段中设置指定的仓库名称，限制该包仅能发布到这个仓库。仓库名称在 Cargo 配置文件中定义，若未指定，会使用 registry.default 配置项定义的默认仓库；若未设置默认仓库且未使用该选项，publish 字段不会配置，意味着包的发布不受限制。

显示选项（Display Options）

-v /--verbose：启用详细输出。可指定两次以开启 "超详细输出"，包含依赖警告、构建脚本输出等额外信息，也可通过配置项 term.verbose 启用。
-q /--quiet：不打印 Cargo 的日志信息，也可通过配置项 term.quiet 启用。
--color when：控制是否使用彩色输出，有效值如下：
- auto（默认）：自动检测终端是否支持彩色输出。
- always：始终显示彩色输出。
- never：从不显示彩色输出。该选项也可通过配置项 term.color 设置。

通用选项（Common Options）

+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 可查看详细说明。

环境变量（ENVIRONMENT）

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

退出状态（EXIT STATUS）

0：Cargo 执行成功。
101：Cargo 执行失败。

示例（EXAMPLES）

在当前目录创建二进制 Cargo 包：cargo init

cargo-install（构建并安装 Rust 二进制文件）

名称（NAME）

cargo-install --- 构建并安装 Rust 二进制文件

语法（SYNOPSIS）

cargo install [选项] crate [@版本]...cargo install [选项] --path 路径cargo install [选项] --git 链接 [crate...]cargo install [选项] --list

说明（DESCRIPTION）

该命令用于管理 Cargo 本地安装的二进制 crate 包。仅包含可执行目标（[[bin]] 或 [[example]]）的包可被安装，所有可执行文件会安装到 "安装根目录" 的 bin 文件夹中。默认仅安装二进制文件，不安装示例文件。

"安装根目录" 的确定优先级如下：

--root 选项
CARGO_INSTALL_ROOT 环境变量
install.root 配置值
CARGO_HOME 环境变量
$HOME/.cargo

crate 包的安装来源有多种，默认来源是 crates.io，但可通过 --git、--path、--registry 标志切换来源。如果来源包含多个包（如 crates.io 或包含多个 crate 的 git 仓库），需指定 crate 参数以明确要安装的包。

从 crates.io 安装时，可通过 --version 标志指定版本；从 git 仓库安装时，可指定分支、标签或提交记录。若一个 crate 包含多个二进制文件，可通过 --bin 选项选择仅安装其中一个；若想安装示例文件，可使用 --example 选项。

如果包已安装，只有当已安装版本 "非最新" 时，Cargo 才会重新安装。出现以下任一情况时，Cargo 会触发重新安装：

包的版本或来源发生变化。
已安装的二进制文件名集合变化。
启用的功能（features）变化。
编译配置文件（--profile）变化。
目标架构（--target）变化。

通过 --path 安装时，除非存在来自其他包的冲突二进制文件，否则会始终重新构建并安装。可使用 --force 标志强制 Cargo 重新安装包。

若来源是 crates.io 或 --git，默认会在临时目标目录中构建包。若想避免此行为，可将 CARGO_TARGET_DIR 环境变量设为相对路径，这在持续集成（CI）系统中缓存构建产物时非常实用。

关于锁文件（Dealing with the Lockfile）

默认情况下，包自带的 Cargo.lock 文件会被忽略。这意味着 Cargo 会重新计算依赖版本，可能会使用包发布后更新的依赖版本。

可使用 --locked 标志强制 Cargo 使用包自带的 Cargo.lock 文件（若存在）。该标志适用于需要 "可复现构建" 的场景（确保使用与包发布时完全一致的依赖），也可解决 "新依赖版本无法在本地构建" 等问题。但使用 --locked 的缺点是无法获取依赖的修复或更新。

注：Cargo 从 1.37 版本开始才支持发布包时附带 Cargo.lock 文件，因此 1.37 之前版本发布的包没有该文件。

配置查找（Configuration Discovery）

该命令作用于 "系统级" 或 "用户级" 配置，而非 "项目级"。这意味着会忽略本地项目的配置，仅从 $CARGO_HOME/config.toml 开始查找配置。若通过 --path$ PATH 安装包，则会使用本地配置，从 $PATH/.cargo/config.toml 开始查找。

选项（OPTIONS）

安装选项（Install Options）

--vers version /--version version：指定要安装的版本。可传入版本约束（如～1.2，让 Cargo 选择该约束下的最新版本）；若版本号无约束运算符（如 ^ 或～），则必须是 MAJOR.MINOR.PATCH 格式（如 1.2.3），且会安装该精确版本（不按 Cargo 依赖的 "caret 约束" 处理）。
--git url：从指定的 git 链接安装 crate。
--branch branch：从 git 仓库的指定分支安装。
--tag tag：从 git 仓库的指定标签安装。
--rev sha：从 git 仓库的指定提交记录（SHA 值）安装。
--path path：从本地文件系统的指定路径安装 crate。
--list：列出所有已安装的包及其版本。
-n /--dry-run：（不稳定）执行所有检查，但不实际安装。
-f /--force：强制覆盖已存在的 crate 或二进制文件。适用于 "不同包安装了同名二进制文件" 的场景，也可用于 "系统环境变化后需要重新构建" 的情况（如 rustc 版本更新）。
--no-track：默认情况下，Cargo 会通过 "安装根目录下的元数据文件" 跟踪已安装包。该标志会让 Cargo 不使用、不创建该文件，且除非配合 --force，否则会拒绝覆盖任何已存在的文件。同时，该标志会禁用 Cargo 对 "多个并发安装进程" 的保护。
--bin name...：仅安装指定名称的二进制文件。
--bins：安装所有二进制文件，这是默认行为。
--example name...：仅安装指定名称的示例文件。
--examples：安装所有示例文件。
--root dir：指定安装包的目标目录。
--registry registry：指定使用的仓库名称，仓库名称在 Cargo 配置文件中定义。若未指定，使用默认仓库（由 registry.default 配置项定义，默认是 crates-io）。
--index index：指定仓库索引的 URL。

功能选择（Feature Selection）

功能标志用于控制启用哪些功能。若未指定任何功能选项，会为所有选中的包启用默认功能（default feature）。详细可查看 "功能" 相关文档。

-F features /--features features：启用指定的功能，多个功能用空格或逗号分隔。工作区成员的功能可通过 "包名 / 功能名" 格式启用（如 pkg1/feat1）。该选项可多次指定，启用所有指定的功能。
--all-features：启用所有选中包的所有可用功能。
--no-default-features：不为选中的包启用默认功能。

编译选项（Compilation Options）

--target triple：为指定的架构安装包，默认是主机架构。架构三元组（triple）的通用格式为 <arch><sub>-<vendor>-<sys>-<abi>，运行 rustc --print target-list 可查看所有支持的架构。该选项也可通过 build.target 配置项设置。注：指定该标志后，Cargo 会切换到 "单独目标模式"，目标产物会放在独立目录中，详细可查看 "构建缓存" 文档。
--target-dir directory：指定生成产物和中间文件的目录。可通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置项设置，默认是系统临时目录下的新文件夹。通过 --path 安装时，默认使用本地 crate 工作区中的 target 目录（除非指定 --target-dir）。
--debug：使用 dev 配置文件构建，而非 release 配置文件。也可通过 --profile 选项指定具体的配置文件名称。
--profile name：使用指定的配置文件安装，详细可查看 "配置文件" 参考文档。
--timings=fmts：输出 "每个编译步骤的耗时"，并跟踪并发信息。可传入可选的、逗号分隔的输出格式；若仅写 --timings，默认等同于 --timings=html。指定输出格式（非默认）属于不稳定功能，需启用 -Zunstable-options 标志。有效值如下：
- html（不稳定，需 -Zunstable-options）：在 target/cargo-timings 目录下生成人类可读的 cargo-timing.html 报告，同时生成带时间戳的历史报告（方便查看旧记录）。HTML 报告仅适用于人工阅读，不提供机器可读的时序数据。
- json（不稳定，需 -Zunstable-options）：输出机器可读的 JSON 格式时序信息。

清单选项（Manifest Options）

--ignore-rust-version：忽略包中的 rust-version 声明。
--locked：确保使用的依赖及版本与现有 Cargo.lock 文件生成时完全一致。出现以下情况时，Cargo 会报错退出：
1. 缺少锁文件。
2. Cargo 因依赖解析变化尝试修改锁文件。该选项适用于需要 "确定性构建" 的环境（如 CI 流水线）。
--offline：禁止 Cargo 以任何理由访问网络。未使用该标志时，若需要联网但网络不可用，Cargo 会报错退出；使用该标志后，Cargo 会尝试在无网络的情况下继续执行。注：该模式下的依赖解析可能与在线模式不同，Cargo 会仅使用本地已下载的 crate，即使本地索引显示有更新版本。可先运行 cargo-fetch (1) 命令下载依赖，再进入离线模式。该选项也可通过 net.offline 配置项设置。
--frozen：等同于同时指定 --locked 和 --offline。

其他选项（Miscellaneous Options）

-j N /--jobs N：指定并行执行的任务数，可通过 build.jobs 配置项设置，默认等于逻辑 CPU 核心数。若为负数，任务数为 "逻辑 CPU 数 + 该负数"；若传入字符串 default，恢复默认值。不可设为 0。
--keep-going：尽可能构建依赖图中的所有 crate，而非在第一个构建失败时就终止。例如：若当前包依赖两个 crate，其中一个构建失败，使用 cargo install -j1 可能不会构建另一个（取决于 Cargo 执行顺序），而 cargo install -j1 --keep-going 会确保两个都执行，即使第一个失败。

显示选项（Display Options）

-v /--verbose：启用详细输出。可指定两次以开启 "超详细输出"，包含依赖警告、构建脚本输出等额外信息，也可通过配置项 term.verbose 启用。
-q /--quiet：不打印 Cargo 的日志信息，也可通过配置项 term.quiet 启用。
--color when：控制是否使用彩色输出，有效值如下：
- auto（默认）：自动检测终端是否支持彩色输出。
- always：始终显示彩色输出。
- never：从不显示彩色输出。该选项也可通过配置项 term.color 设置。
--message-format fmt：诊断信息的输出格式，可多次指定，格式值用逗号分隔。有效值如下：
- human（默认）：人类可读的文本格式，与 short、json 互斥。
- short：简洁的人类可读文本格式，与 human、json 互斥。
- json：向标准输出（stdout）输出 JSON 格式信息，详细可查看参考文档，与 human、short 互斥。
- json-diagnostic-short：确保 JSON 信息的 rendered 字段包含 rustc 的 "简洁" 格式诊断内容，不可与 human、short 同时使用。
- json-diagnostic-rendered-ansi：确保 JSON 信息的 rendered 字段包含嵌入 ANSI 颜色码的内容（符合 rustc 默认配色），不可与 human、short 同时使用。
- json-render-diagnostics：让 Cargo 不将 rustc 的诊断信息包含在 JSON 输出中，而是自行渲染 rustc 传来的 JSON 诊断内容。Cargo 自身的 JSON 诊断信息仍会输出，不可与 human、short 同时使用。

通用选项（Common Options）

（与 cargo-init (1) 的 "通用选项" 内容一致，此处略去以避免重复，可参考上文）

环境变量（ENVIRONMENT）

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

退出状态（EXIT STATUS）

0：Cargo 执行成功。
101：Cargo 执行失败。

示例（EXAMPLES）

从 crates.io 安装或升级包：cargo install ripgrep
安装或重新安装当前目录下的包：cargo install --path .
查看已安装的包列表：cargo install --list

cargo-new（创建新的 Cargo 包）

名称（NAME）

cargo-new --- 创建新的 Cargo 包

语法（SYNOPSIS）

cargo new [选项] 路径

说明（DESCRIPTION）

该命令会在指定路径的目录中创建新的 Cargo 包，包含以下内容：

一个简单的模板（含 Cargo.toml 清单文件）。
示例源文件。
版本控制系统忽略文件（如 .gitignore）。

如果该目录尚未加入任何版本控制系统（VCS），会自动创建一个新的版本库（具体可查看下方 --vcs 选项说明）。

类似命令可参考 cargo-init (1)，它会在已存在的目录中创建新的 Cargo 清单文件。

选项（OPTIONS）

新建选项（New Options）

--bin：创建包含二进制目标文件（src/main.rs）的包，这是默认行为。
--lib：创建包含库目标文件（src/lib.rs）的包。
--edition edition：指定使用的 Rust 版本。默认是 2024，可选值包括 2015、2018、2021、2024。
--name name：设置包的名称，默认使用目录名。
--vcs vcs：为指定的版本控制系统（git、hg、pijul 或 fossil）初始化新仓库，也可指定为 none（不初始化任何版本控制）。若未指定，默认使用 git 或配置值 cargo-new.vcs；如果目录已在版本控制仓库内，则默认不初始化（none）。
--registry registry：在 Cargo.toml 的 publish 字段中设置指定的仓库名称，限制该包仅能发布到这个仓库。仓库名称在 Cargo 配置文件中定义，若未指定，会使用 registry.default 配置项定义的默认仓库；若未设置默认仓库且未使用该选项，publish 字段不会配置，意味着包的发布不受限制。

显示选项（Display Options）

（与 cargo-init (1) 的 "显示选项" 内容一致，此处略去）

通用选项（Common Options）

（与 cargo-init (1) 的 "通用选项" 内容一致，此处略去）

环境变量（ENVIRONMENT）

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

退出状态（EXIT STATUS）

0：Cargo 执行成功。
101：Cargo 执行失败。

示例（EXAMPLES）

在指定目录创建二进制 Cargo 包：cargo new foo

cargo-search（在仓库中搜索包）

名称（NAME）

cargo-search --- 在仓库中搜索包，默认仓库是 crates.io

语法（SYNOPSIS）

cargo search [选项] [查询词...]

说明（DESCRIPTION）

该命令会在 https://crates.io 上对 crate 进行文本搜索，搜索结果会附带包的描述，且以 TOML 格式展示（方便直接复制到 Cargo.toml 清单文件中）。

选项（OPTIONS）

搜索选项（Search Options）

--limit limit：限制搜索结果数量，默认 10 条，最多 100 条。
--index index：指定使用的仓库索引 URL。
--registry registry：指定使用的仓库名称，仓库名称在 Cargo 配置文件中定义。若未指定，使用默认仓库（由 registry.default 配置项定义，默认是 crates-io）。

显示选项（Display Options）

（与 cargo-init (1) 的 "显示选项" 内容一致，此处略去）

通用选项（Common Options）

（与 cargo-init (1) 的 "通用选项" 内容一致，此处略去）

环境变量（ENVIRONMENT）

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

退出状态（EXIT STATUS）

0：Cargo 执行成功。
101：Cargo 执行失败。

示例（EXAMPLES）

从 crates.io 搜索包：cargo search serde

cargo-uninstall（卸载 Rust 二进制文件）

名称（NAME）

cargo-uninstall --- 卸载 Rust 二进制文件

语法（SYNOPSIS）

cargo uninstall [选项] [包规格...]

说明（DESCRIPTION）

该命令用于卸载通过 cargo-install (1) 安装的包。"包规格" 参数是待卸载包的包 ID 规格（具体可查看 cargo-pkgid (1)）。

默认会卸载一个 crate 的所有二进制文件，但可通过 --bin 和 --example 标志选择仅卸载特定的二进制文件或示例文件。

"安装根目录" 的确定优先级如下：

--root 选项
CARGO_INSTALL_ROOT 环境变量
install.root 配置值
CARGO_HOME 环境变量
$HOME/.cargo

选项（OPTIONS）

卸载选项（Uninstall Options）

-p /--package spec...：指定要卸载的包。
--bin name...：仅卸载指定名称的二进制文件。
--root dir：指定要卸载包的来源目录（即当初安装时的 "安装根目录"）。

显示选项（Display Options）

（与 cargo-init (1) 的 "显示选项" 内容一致，此处略去）

通用选项（Common Options）

（与 cargo-init (1) 的 "通用选项" 内容一致，此处略去）

环境变量（ENVIRONMENT）

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

退出状态（EXIT STATUS）

0：Cargo 执行成功。
101：Cargo 执行失败。

示例（EXAMPLES）

卸载之前安装的包：cargo uninstall ripgrep