Rust 操作与命令 · 选择依赖、更新锁文件与准备离线构建至格式化、静态检查与自动修复

返回分篇目录

本轮仅静态审读，未执行工具链或示例命令。成对双花括号中的内容是待替换参数，短选项与长选项并列时表示任选一种写法，不要原样复制。下列命令会按用途安装、改写配置、编译或发布，运行前先确认当前目录、目标工具链与操作影响。

选择依赖、更新锁文件与准备离线构建

先搜索和查看包信息，再添加/移除依赖；锁文件、依赖图、下载和 vendor 分别保留，避免把下载与更新混为同一操作。

cargo search · 在 <https://crates.io> 上搜索包

显示包及其描述，以 TOML 格式显示，可复制到 Cargo.toml 中。 更多信息：https://doc.rust-lang.org/cargo/commands/cargo-search.html。

• 搜索包：

cargo search {{查询词}}

• 显示 n 个结果 (默认为 10，最多为 100)：

cargo search --limit {{n}} {{查询词}}

cargo info · 显示 Rust 软件包的信息

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-info.html。

• 显示 https://crates.io 上一个软件包的信息：

cargo info {{软件包}}

• 显示一个软件包的特定版本的信息：

cargo info {{软件包}}@{{版本}}

• 显示一个软件包的额外信息：

cargo info {{[-v|--verbose]}} {{软件包}}

cargo add · 向 Rust 项目的 Cargo.toml 清单添加依赖项

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-add.html。

• 将最新版本的依赖项添加到当前项目：

cargo add {{依赖项}}

• 添加特定版本的依赖项：

cargo add {{依赖项}}@{{版本号}}

• 添加依赖项并启用一个或多个特定功能：

cargo add {{依赖项}} {{[-F|--features]}} {{功能1,功能2,...}}

• 添加一个可选的依赖项，然后将其作为包（crate）的一个功能暴露出来：

cargo add {{依赖项}} --optional

• 将本地包（crate）添加为依赖项：

cargo add --path {{路径/到/目录}}

• 添加一个开发或构建依赖项：

cargo add {{依赖项}} --{{dev|build}}

• 添加一个禁用所有默认功能的依赖项：

cargo add {{依赖项}} --no-default-features

cargo remove · 从 Rust 项目的 Cargo.toml 清单中移除依赖项

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-remove.html。

• 从当前项目中移除一个依赖项：

cargo remove {{依赖项}}

• 移除开发或构建依赖项：

cargo remove --{{dev|build}} {{依赖项}}

• 移除给定目标平台的依赖项：

cargo remove --target {{目标}} {{依赖项}}

cargo generate-lockfile · 为当前软件包生成 Cargo.lock 文件。类似于 cargo update，但选项更少

如果锁定文件已经存在，它将使用每软件包的最新版本重新构建。 更多信息：https://doc.rust-lang.org/stable/cargo/commands/cargo-generate-lockfile.html。

• 使用每个软件包的最新版本生成 Cargo.lock 文件：

cargo generate-lockfile

cargo update · 更新记录在 Cargo.lock 中的依赖关系

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-update.html。

• 将 Cargo.lock 中的依赖项更新为可能的最新版本：

cargo update

• 显示将会更新的内容，但实际上不写入锁定文件：

cargo update {{[-n|--dry-run]}}

• 仅更新指定的依赖项：

cargo update --package {{依赖项1}} --package {{依赖项2}} --package {{依赖项3}}

• 将特定依赖项设置为特定版本：

cargo update --package {{依赖项}} --precise {{1.2.3}}

cargo tree · 显示依赖图的树形可视化

注意：在树中，标有 (*) 的包的依赖已在图的其他位置显示过，因此不会重复显示。 更多信息：https://doc.rust-lang.org/cargo/commands/cargo-tree.html。

• 显示当前项目的依赖树：

cargo tree

• 仅显示到指定深度的依赖 (例如，当 n 为 1 时，仅显示直接依赖)：

cargo tree --depth {{n}}

• 在树中不显示给定的包（及其依赖)：

cargo tree --prune {{package_spec}}

• 显示重复依赖的所有出现：

cargo tree --no-dedupe

• 仅显示 normal/build/dev 依赖：

cargo tree {{[-e|--edges]}} {{normal|build|dev}}

cargo metadata · 以 JSON 格式输出当前软件包的工作空间成员和已解析的依赖项

注意：输出格式可能在未来的 Cargo 版本中发生变化。 更多信息：https://doc.rust-lang.org/cargo/commands/cargo-metadata.html。

• 打印当前软件包的工作空间成员和已解析的依赖项：

cargo metadata

• 仅打印工作空间成员，不获取依赖项：

cargo metadata --no-deps

• 根据指定版本打印特定格式的元数据：

cargo metadata --format-version {{版本号}}

• 打印带有 resolve 字段的元数据，仅包含给定目标三元组的依赖项（注意：packages 数组仍将包含所有目标的依赖项）：

cargo metadata --filter-platform {{目标三元组}}

cargo pkgid · 打印当前工作空间中软件包或依赖项的完全限定软件包 ID 标识符

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-pkgid.html。

• 打印当前项目的完全限定软件包标识规范：

cargo pkgid

• 打印指定软件包的完全限定软件包标识规范：

cargo pkgid {{部分包标识规范}}

cargo fetch · 从网络获取软件包的依赖项

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-fetch.html。

• 获取 Cargo.lock 中指定的依赖项（对所有目标）：

cargo fetch

• 为指定目标获取依赖项：

cargo fetch --target {{目标三元组}}

cargo vendor · 将项目的所有依赖项存储到指定目录中（默认为 vendor）

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-vendor.html。

下方直接重定向是仅适用于 .cargo 已存在、且确认可以覆盖其配置的旧简写；> 会覆盖文件，不能直接用于已有项目。Bash 中可先用 cargo vendor vendor > vendor-config.toml，检查成功后创建 .cargo 目录，将生成的 [source] 配置人工合并进现有 .cargo/config.toml。先检查是否已有同名 source 表，避免追加重复键；不要删除既有 registry、target 或 build 设置。vendor 目录内容也可能被命令更新，不能混放自行维护的源码。

• 将依赖项存储到指定目录，并配置在当前项目中使用这些存储的源代码：

cargo vendor {{path/to/directory}} > .cargo/config.toml

格式化、静态检查与自动修复

先格式化和检查，再按诊断使用 Clippy 或 fix；report 与 clean 放在诊断/清理末尾。

cargo fmt · 在 Rust 项目中对所有源文件运行 rustfmt

另请参阅：rustfmt。 更多信息：https://github.com/rust-lang/rustfmt。

• 格式化所有源文件：

cargo fmt

• 检查格式错误，不对文件进行写入操作：

cargo fmt --check

• 将参数传递给每个 rustfmt 调用：

cargo fmt -- {{rustfmt参数}}

cargo check · 检查本地软件包及其所有依赖项是否有错误

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-check.html。

• 检查当前软件包：

cargo {{[c|check]}}

• 检查所有测试：

cargo {{[c|check]}} --tests

• 检查 tests/integration_test1.rs 中的集成测试：

cargo {{[c|check]}} --test {{integration_test1}}

• 使用 feature1 和 feature2 功能检查当前软件包：

cargo {{[c|check]}} {{[-F|--features]}} {{feature1,feature2}}

• 禁用默认功能后检测当前软件包：

cargo {{[c|check]}} --no-default-features

cargo clippy · 一系列 lint 工具，用于捕获常见错误并改进 Rust 代码

更多信息：https://github.com/rust-lang/rust-clippy。

• 对当前目录中的代码运行检查：

cargo clippy

• 要求 Cargo.lock 文件是最新的：

cargo clippy --locked

• 对工作区中的所有软件包进行检查：

cargo clippy --workspace

• 对某个软件包进行检查：

cargo clippy --package {{软件包}}

• 运行特定 lint 组的检查（参见 https://rust-lang.github.io/rust-clippy/stable/index.html#?groups=cargo,complexity,correctness,deprecated,nursery,pedantic,perf,restriction,style,suspicious）：

cargo clippy -- {{[-W|--warn]}} clippy::{{lint 组}}

• 将警告视为错误：

cargo clippy -- {{[-D|--deny]}} warnings

• 运行检查并忽略警告：

cargo clippy -- {{[-A|--allow]}} warnings

• 自动应用 Clippy 的建议：

cargo clippy --fix

cargo fix · 自动修复 rustc 报告的 lint 警告

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-fix.html。

• 即使已经有编译器错误，也要修复代码：

cargo fix --broken-code

• 即使工作目录有更改，也要修复代码：

cargo fix --allow-dirty

• 为软件包迁移到下一个 edition 自动修正可处理的源码（不升级编译器）：

cargo fix --edition

完成后还需手动修改 Cargo.toml 的 edition 并重新检查测试；未启用的 feature 或其他平台 cfg 分支可能需要分别处理。自动修复不能替代完整迁移，详见 edition migration。

• 修复软件包的库：

cargo fix --lib

• 修复指定的集成测试：

cargo fix --test {{名称}}

• 修复工作区中的所有成员：

cargo fix --workspace

cargo report · 显示各种类型的报告

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-report.html。

• 显示一份属于未来将无法编译的包（crate）的报告：

cargo report future-incompatibilities

• 显示具有指定 Cargo 生成标识符的报告：

cargo report future-incompatibilities --id {{标识符}}

• 为指定的软件包显示报告：

cargo report future-incompatibilities {{[-p|--package]}} {{软件包}}

cargo clean · 删除 target 目录中生成的构建产物

更多信息：https://doc.rust-lang.org/cargo/commands/cargo-clean.html。

• 删除整个 target 目录：

cargo clean

• 删除文档构建产物（target/doc 目录）：

cargo clean --doc

• 删除 release 模式的构建产物（target/release 目录）：

cargo clean {{[-r|--release]}}

• 删除给定配置文件的目录中的构建产物（在本例中为 target/debug）：

cargo clean --profile {{dev}}