Cargo 入门：创建/构建/运行项目
本教程共 78 篇 · 第 5 篇 · 更新于 2026-08-08 · 约 7 分钟阅读
本节目标：用 cargo 创建第一个正经项目，并掌握 build、run、check 三条最常用命令，从此不再手动敲 rustc。
上一章我们用 rustc main.rs 直接编译，那适合单文件演示。真实开发里，项目有目录结构、有依赖、有构建配置，全靠手敲编译器不现实。Cargo 就是 Rust 官方给的”项目总管”——建项目、编代码、跑程序、拉第三方库，它一手包办。你前面装工具链时 cargo 已经一起装好了。
5-1 用 cargo new 创建项目
找个你喜欢的目录，执行：
cargo new hello_cargo这条命令会创建一个名为 hello_cargo 的文件夹，里面已经铺好了标准骨架。进去看看：
cd hello_cargoNote
cargo new默认生成的是”二进制可执行项目”（带main函数）。如果你想写一个给别人当库用的 crate，加--lib参数：cargo new my_lib --lib。两者结构类似，只是入口文件不同。
5-2 直接运行：cargo run
最常用的一条命令，编译并运行一步到位：
cargo run第一次跑会先编译，然后执行，你会在终端看到：
Compiling hello_cargo v0.1.0 (...\hello_cargo)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.7s
Running `target\debug\hello_cargo.exe`
Hello, world!注意最后那行 Hello, world!，这就是新项目自带的示例代码输出的。cargo 已经替你写了一段打印问候的小程序，省得你从空白起步。
Tip改完代码再
cargo run，它会自动重新编译再运行。开发时这条命令基本是你按得最多的键。
5-3 只编译不运行：cargo build
有时候你只想确认”代码能不能编过""产物有没有生成”，不想跑它：
cargo build编译成功后，可执行文件会出现在 target/debug/ 目录下。你可以脱离 cargo 直接运行它：
# Windows
.\target\debug\hello_cargo.exe
# macOS / Linux
./target/debug/hello_cargocargo build 和 cargo run 的区别就在这：build 只产出文件，run 产出外加执行。
5-4 快速检查：cargo check
写代码过程中，你经常想确认”我刚写的这堆对不对、能不能编过”。每次都用 cargo build 会做完整编译，有点慢。cargo check 应运而生：
cargo check它只做语法和类型检查，不生成最终可执行文件，因此快得多。大型项目里，改一行就用 cargo check 快速验错，确认无误了再 cargo build / cargo run。这是老手的高频习惯。
Note一句话记忆：想跑程序用
run，想出文件用build，只想快点验错用check。
5-5 发布构建：—release
前面 cargo build 编出来的是 debug 版本，没做太多优化、带调试信息，跑得慢一点但编得快。要交付给用户、追求速度时，加 --release：
cargo build --release这次产物在 target/release/ 目录，编译器会做大量优化，跑起来明显更快，代价是编译时间更长。开发和调试用 debug，发布上线用 release，这是基本常识。
5-6 自定义运行参数
cargo run 后面可以跟 -- 再接你的程序参数。比如你的程序需要读一个文件名：
cargo run -- data.txt-- 之后的内容会原样传给你的程序，而不是当成 cargo 自己的参数。这个技巧以后写带命令行参数的程序用得上。
5-7 版本号与项目名规矩
cargo new 取的项目名会写进配置文件，Rust 要求 crate 名只能含字母、数字、横杠 -（不能下划线，也不能中文）。如果你用 cargo new my_project，它会自动把下划线改成横杠 my-project。起名时直接用横杠最省事。
Warning新手常把
cargo run敲成cargo run hello_cargo（带上项目名），结果报错。cargo 在当前项目目录里执行，不需要你告诉它项目叫什么。直接cargo run即可。
5-8 运行和阅读别人的项目
学会建自己的项目后，你很快会想读别人写的 Rust 代码来学习。绝大多数开源 Rust 项目都用 cargo 管理，拿到源码后流程高度一致。从 GitHub 克隆一个项目后，进目录第一件事通常是先 cargo build 确认它能编过，再 cargo run 看效果。
很多库项目会在 examples/ 目录放可运行的示例程序。用 cargo run --example 示例名 能单独跑某个示例，比直接啃文档直观得多。比如某个网络库可能提供了 examples/client.rs，你跑 cargo run --example client 就能看到它怎么用。
Tip想快速浏览一个库的公开 API，在项目目录跑
cargo doc --open，它会根据源码里的///注释生成网页文档，比在 GitHub 网页翻源码方便。另一个高频命令是cargo test，会运行项目里所有测试（含文档示例），clone 下来先cargo test跑一遍能确认环境没问题。
新手常忽略一点：第一次 cargo build 别人的项目，会下载并编译一大堆依赖，可能要等上几分钟。这很正常，不是卡死了——Rust 把依赖源码拉下来挨个编译，依赖多时耗时明显。等第一次编完，后续因为有了缓存会快很多。
Warning跑别人项目前，先看根目录有没有
README.md和Cargo.toml里的edition字段。如果对方是基于很旧的 Edition 写的，你用新版 cargo 打开可能报一批过时语法错误。这时要么按报错逐个改，要么用rustup切到对方标注的版本再试。
5-9 cargo 命令速查表
把本章和前面提到的 cargo 命令汇总成一张速查表，方便你随时回看：
| 命令 | 作用 |
|---|---|
cargo new 名 | 创建新项目 |
cargo build | 编译（debug） |
cargo run | 编译并运行 |
cargo check | 只检查不编译成品 |
cargo build --release | 优化编译（release） |
cargo test | 运行测试 |
cargo doc --open | 生成并打开文档 |
Tip记不住命令就
cargo --help，它会列出所有子命令；想知道某个子命令的细节，用cargo build --help这种”命令后加 —help”也通用。cargo 的命令行设计很一致，学会一个就学会套路。
5-10 给程序传命令行参数
cargo run 后面可以跟程序参数，这在写”接收命令行输入”的小工具时很常用。比如你的程序要根据用户输入的名字问候，运行时这样传：cargo run -- 小明。注意 -- 是分隔符，它告诉 cargo”后面的都是给程序的参数、不是给 cargo 的”。漏掉 -- 时，小明 可能被 cargo 误当成自己的选项而报错。这个细节新手常栽。
Note参数解析在正式项目里通常用
std::env::args()或第三方库（如clap）来做。入门阶段你只要知道”cargo run — 参数”这招能让你写的程序接收外部输入，后面需要时再深入即可。
5-11 小结
到这你已经掌握了 cargo 的四条命根子命令：new 建项目、build 编文件、run 编加跑、check 快验错。配合 --release 区分调试和发布。下一章我们打开项目骨架，看清 cargo 到底在你的文件夹里摆了哪些东西、各自干嘛用。