Reference 速查清单：Cargo 从项目创建、测试到发布的完整实战指南-平芜编程栈

Reference 速查清单：Cargo 从项目创建、测试到发布的完整实战指南

【免费下载链接】reference面向开发者的技术速查清单（Cheat Sheets）集合，整理常见技术、工具与开发流程，帮助快速查阅关键信息，提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference

Cargo 是 Rust 生态的官方构建工具与包管理器，也是日常 Rust 开发使用频率最高的命令行工具。本文基于 Reference 速查清单仓库中的 Cargo 备忘清单整理扩充，覆盖 Rust 工具链安装、核心命令速查、国内镜像源切换、项目创建与编译、Cargo.toml目标配置、测试过滤，直至打包、发布与 yank 撤回的完整生命周期。读完本篇，你可以独立完成一个 Rust 项目的创建、构建、测试与发布，并能熟练查阅仓库配套清单深入相关主题。

安装与版本确认

在 Linux 与 macOS 上，推荐通过官方工具链管理脚本 rustup 一次性安装 Rust 编译器与 Cargo（Cargo 清单）：

$ curl -sSf https://static.rust-lang.org/rustup.sh | sh

安装完成后，用版本命令确认工具链已就绪：

$ cargo version

相关资源可参考：Cargo 开源仓库与官方手册（Cargo Book）、Rust 社区的 crate 仓库 crates.io，以及 Cargo 手册中文版（rustwiki）。Rust 语言本身的语法速查可继续查阅本仓库的 Rust 备忘清单。

核心命令速查

速查清单汇总了日常使用频率最高的 9 条命令，适合作为开发时的第一反应表：

从命令结构看，cargo check只执行类型检查与依赖解析而不产出可执行文件，因此是大型项目中迭代排错时最快的反馈循环；cargo fmt与cargo clippy属于 Rust 工具链的可扩展组件，通常需要通过 rustup 安装对应组件后方可使用；cargo tarpaulin则是第三方覆盖率工具，需另行安装。

切换国内镜像源

crates.io 的官方索引在国内访问缓慢，速查清单给出了通过本地配置文件切换镜像源的完整步骤。

创建并编辑配置文件

$ touch ~/.cargo/config # 添加配置文件 $ vim ~/.cargo/config # 编辑配置文件

配置文件内容

将默认源crates-io通过replace-with指向清华 TUNA 镜像：

[source.crates-io] registry = "https://github.com/rust-lang/crates.io-index" replace-with = 'tuna' # 👈 如果需要提交包注释配置源 [source.tuna] registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git" # registry = "git://mirrors.ustc.edu.cn/crates.io-index"

其中replace-with字段声明了“使用crates-io时实际改走tuna源”的替换关系；注释掉replace-with即可在需要向 crates.io 提交（publish）时恢复官方源，这也是速查清单注释的提示。文件末尾同时保留了中科大镜像的备选地址，可按网络环境切换。

清理缓存（关键步骤）

切换源之后必须删除旧的包缓存，否则仍可能命中旧索引数据（速查清单）：

$ rm -rf ~/.cargo/.package-cache # ⚠️ 删除缓存目录内容

注意：该命令删除的是缓存目录内容，请在确认路径后再执行。较新版本的 Cargo 亦支持.cargo/config.toml作为等效配置文件名，两者行为一致。

创建新项目

生成项目骨架

使用cargo new创建二进制程序（速查清单）：

$ cargo new hello_world --bin

目标类型参数：

--bin：正在制作一个二进制程序（默认行为）
--lib：正在创建一个库（lib）

得到的标准目录结构：

$ cd hello_world $ tree . . ├── Cargo.toml └── src └── main.rs

理解 Cargo.toml 清单

Cargo.toml被称为一个manifest（元清单），它包含了 Cargo 编译项目所需的所有元数据：

[package] name = "hello_world" version = "0.1.0" authors = ["Your Name <you@example.com>"] edition = "2018" [dependencies]

入口文件src/main.rs：

fn main() { println!("Hello, world!"); }

edition字段决定语言版本，常见取值为2015、2018、2021（cargo init --edition的默认值为2021）。Cargo.toml是 TOML 格式文件，其完整语法可查阅本仓库的 TOML 备忘清单。

编译并运行

$ cargo build # 文件放入 `target/release` 目录 $ cargo build --release

然后直接执行生成的二进制：

$ ./target/debug/hello_world Hello, world!

也可以直接使用cargo run，它会自行编译并运行项目：

$ cargo run Running `target/hello_world` Hello, world!

约定上，debug 产物落在target/debug/，--release优化产物落在target/release/；target/目录通常加入版本控制的忽略清单。

源（Source）配置详解

速查清单给出了更完整的[source]配置示例，展示了本地目录源、Git 源与源替换的组合方式：

# `source` 表下，就是存储有关要更换的来源名称 [source] # 在`source` 表格之下的，可为一定数量的有关来源名称。示例下面就，定义了一个新源， 叫 `my-awesome-source`，其内容来自本地 `vendor` 目录，其相对于包含 `.cargo/config` 文件的目录 [source.my-awesome-source] directory = "vendor" # Git sources 也指定一个 branch/tag/rev git = "https://example.com/path/to/repo" # branch = "master" # tag = "v1.0.1" # rev = "313f44e8" # crates.io 默认源 在"crates-io"名称下，且在这里我们使用 `replace-with` 字段指明 默认源更换成"my-awesome-source"源 [source.crates-io] replace-with = "my-awesome-source"

源定义支持几种类型，速查清单列出了全套可用字段：

# 每个源都有自己的表格，名称即是表名 [source.the-source-name] # 命令 `the-source-name` 会被 `another-source` 取代 replace-with = "another-source" # 有几种可用的源定义(接下来有所描述) registry = "https://example.com/path/to/index" local-registry = "path/to/registry" directory = "path/to/vendor"

更换源的配置通过完成.cargo/config文件实现。directory源适合企业内网离线构建（将依赖 vendored 到本地目录），Git 源可通过branch/tag/rev精确锁定版本，registry源则指向任意兼容 crates.io 索引协议的仓库。

配置目标（[lib] 表）

当一个 crate 包含库目标时，可在Cargo.toml中用[lib]表精细控制其构建行为（速查清单）：

[package] # ... [lib] # 生成目标与库的名称。本该默认是包名, 替换所有破折号为 下划线。(Rust `extern crate` 声明会参考该名；因此，该值必须是可用的有效Rust标识符) name = "foo" # 该字段，指向 crate 的入口(位置), 路径相对于 `Cargo.toml`. path = "src/lib.rs" # 一个给目标启用单元测试 的 标志. 会被 `cargo test`使用. test = true # 一个给目标启用文档测试 的 标志. 只与库相关, 不会影响其他部分。会被 `cargo test`使用. doctest = true # 一个给目标启用基准 的 标志. 会被 `cargo bench`使用. bench = true # 一个给目标启用文档 的 标志. 会被 `cargo doc`使用. doc = true # 若该目标为 编译器扩展, 那要把该字段设为 true，以让 Cargo 正确编译和，可用于所有依赖项. plugin = false # 若该目标为 "macros 1.1" 程序宏, 那要把该字段设为 true proc-macro = false # 若设为 false, `cargo test` 会为 rustc 省略 `--test` 标志, 这阻止它生成测试工具。这在二进制存在，构建管理测试运行器本身的情况下，有用. harness = true # 若设置了，那 目标会使用一个与`[package]`配置不同的版本, 也许是，编译一个库 2018年版本或，编译单元测试的2015年版本. 默认情况下所有目标都使用`[package]`中指定的版本进行编译。 edition = '2015'

几个关键影响点值得强调：test与doctest决定cargo test是否生成对应的单元测试与文档测试二进制；proc-macro = true是编写程序宏 crate 的必备声明；harness = false则用于自管测试运行器的场景（此时 Cargo 不再为 rustc 附加--test标志）。

项目目录约定

一个功能完整的 Cargo 项目目录布局如下（速查清单）：

. ├── Cargo.lock ├── Cargo.toml ├── benches # 基准目录 │ └── large-input.rs ├── examples # 示例 │ └── simple.rs ├── src # 源代码 │ ├── bin │ │ └── another_executable.rs │ ├── lib.rs # 默认库 │ └── main.rs # 入口文件 └── tests # 集成测试 └── some-integration-tests.rs

从目录结构可以读出 Cargo 的约定：src/main.rs是二进制入口，src/lib.rs是库入口，src/bin/下的每个文件是额外可执行目标；tests/存放集成测试（会作为独立 crate 链接本库），benches/与examples/分别对应cargo bench与示例运行。Cargo.lock记录解析后的精确依赖版本，通常约定随仓库提交以保证可复现构建。

编译与测试

编译输出

# 编译输出二进制文件，放入 `target/debug` 目录 $ cargo build # 输出二进制文件，放入 `target/release` 目录 $ cargo build --release $ cargo run # 编译并运行

测试过滤

cargo test默认运行全部测试，并支持通过过滤器精确选择（速查清单）：

$ cargo test # 运行你的所有测试 # 指定函数过滤器 $ cargo test test_foo # 开头是 test_foo 的函数都会运行，例如(test_foo_bar) # 指定特定模块中的测试函数(通常可以简写 cargo test foo::bar::tests::test_foo) $ cargo test --package rustt --lib -- foo::bar::tests::test_foo --exact --nocapture # 指定特定测试的模块(通常可以简写 cargo test foo::bar::tests) $ cargo test --package rustt --lib -- foo::bar::tests --nocapture

参数要点：--package <name>指定工作区中的包，--lib限定为库目标，--之后的参数透传给底层测试运行器，--exact要求过滤器精确匹配（而非前缀匹配），--nocapture让测试中的println!输出直接显示到终端，便于调试。

包管理命令

cargo init / cargo new

在已有目录或新目录中初始化包（速查清单）：

$ cargo init [options] [path] $ cargo new [options] [path]

常用选项：

--bin：创建具有二进制目标（src/main.rs）的包（默认行为）
--lib：使用库目标（src/lib.rs）创建一个包
--edition edition：指定要使用的 Rust 版本，默认值为2021，可能的值：2015、2018、2021
--name name：设置包名，默认为目录名称
--vcs vcs：为给定的版本控制系统（git、hg、pijul 或 fossil）初始化一个新的 VCS 存储库，或者根本不初始化任何版本控制（none）
--registry registry：限制仅发布到该注册表

典型用法：

$ cargo new foo

安装包

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

（速查清单）可选参数：

--vers version/--version version：指定要安装的版本
--git url：用于安装指定 crate 的 Git URL
--branch branch：从 git 安装时要使用的分支
--tag tag：从 git 安装时使用的标记
--rev sha：从 git 安装时使用的特定提交
--path path：要安装的本地 crate 的文件系统路径
--list：列出所有已安装的软件包及其版本
-f,--force：强制覆盖现有的 crate 或二进制文件

cargo install安装的是可执行产物（安装到~/.cargo/bin），与cargo add这类“添加项目依赖”的操作不同，后者写入的是Cargo.toml的[dependencies]。

搜索包

$ cargo search [options] [query...]

--limit limit：限制结果数量（默认值：10，最大值：100）
--index index：要使用的注册表索引的 URL
--registry registry：要使用的注册表的名称

$ cargo search serde

卸载包

$ cargo uninstall [options] [spec...]

-p,--package spec...：要卸载的软件包
--bin name...：仅卸载二进制名称
--root dir：从中卸载软件包的目录

$ cargo uninstall ripgrep

发布命令

登录与通用输出选项

$ cargo login [options] [token]

--registry：要使用的注册表的名称

通用输出选项（速查清单）：

所有者管理

# 列出包的所有者： $ cargo owner --list foo # 邀请所有者加入包： $ cargo owner --add username foo # 从包中删除所有者： $ cargo owner --remove username foo

（速查清单）

| 选项 | 说明 | | :- | :- | |--token token| 身份验证时使用的 API 令牌 | |--index index| 要使用的注册表索引的 URL |

打包与发布公共选项

以下选项组在cargo package、cargo publish等命令间共享（速查清单）：

选择包

-p spec...,--package spec...：指定包
--workspace：工作区中的全体成员
--exclude SPEC...：排除指定包

编译选项

--target triple：为指定架构执行打包
--target-dir directory：用于存放生成的工件以及中间文件的目录

特性选择

--features features：传递以空格或者逗号分隔的列表，其中给出要启用的特性
--all-features：为给定的包启用全部可用特性
--no-default-features：不启用给定包的 default 特性

清单选项

--manifest-path path：用于指定 Cargo.toml 文件的路径
--frozen,--locked：这两个选项用于保证 Cargo.lock 文件是最新的
--offline：禁止 Cargo 访问网络

混杂选项

-j N,--jobs N：要并行运行的作业数量

--features三件套是发布可选功能 crate 的核心：通过default特性组合控制默认启用的功能集，--no-default-features与--all-features常用于发布前对不同特性组合做编译验证。

打包

将本地包打包为可分发的压缩文件（速查清单）：

$ cargo package [options]

-l,--list：输出包中包含的文件（不实际进行打包）
--no-verify：构建包时不进行校验
--no-metadata：忽略缺少可读的元信息（如描述信息或采用的授权协议）时产生的警告
--allow-dirty：允许打包在版本控制系统中仍有未提交内容的包

发布

$ cargo publish [options]

发布选项（速查清单）：

推荐实践：先用cargo package验证打包内容，再以cargo publish --dry-run走一遍完整检查，最后正式发布。

yank：撤回已发布版本

从服务器的索引中删除以前发布的 crate 版本（速查清单）：

$ cargo yank --vers 1.0.7 foo

--vers version：要 yank 或 un-yank 的版本
--undo：撤消 yank，将版本放回索引中
--token token：身份验证时使用的 API 令牌
--index index：要使用的注册表索引的 URL
--registry registry：要使用的注册表名称

yank 并不真正删除包内容，而是将其从索引中标记为不可再被新解析（已有依赖该版本的下游项目仍可构建），是发布事故（如误发布含敏感信息的版本）后的标准补救手段。

延伸阅读与仓库配套资源

更深入的语义与子命令参考请阅读官方 Cargo Book（The Cargo Book）及其中文版（rustwiki）
Rust 语言语法、类型、集合与模式匹配速查：Rust 备忘清单
Cargo.toml所依赖的 TOML 语法细节（表、数组、日期等）：TOML 备忘清单
本文整理自 Reference 速查清单仓库的 Cargo 备忘清单，该文档在 README 的"软件包管理器"分类中与 APT、Conan、Homebrew、YUM 等包管理工具并列收录；整个清单站点由 package.json 定义的refs-cli构建管线将docs/下的 Markdown 生成静态页面，并通过 netlify.toml 配置发布

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Reference 速查清单：Cargo 从项目创建、测试到发布的完整实战指南