接手一个 Rust 项目,最常见的第一个卡点不是语法,而是环境。同事说「我这边能跑」,你 clone 下来执行 cargo build,终端滚了三百行,最后停在一句 error: linker `link.exe` not found。或者另一种:项目里的 edition 写的是 2021,你本地新装的工具链默认生成 2024 的项目,两个项目混在一起,复制过去的代码报了一堆莫名其妙的错。
这类问题都不难解决,但它们会反复出现,因为 Rust 的项目不只是源码:还有工具链版本、edition、依赖版本、feature 开关、构建 profile。这些东西没有一处写在代码里,却直接决定代码能不能编译、运行时是什么行为。
这篇把这条链路从头走一遍:装工具链、建项目、看懂 Cargo.toml、加一个真实依赖、理解 Cargo.lock、用对常用命令。示例按 Rust 2021 edition 写,本机实测工具链是 rustc 1.99.0。
rustup 装的到底是什么
Rust 官方推荐用 rustup 管理工具链,而不是单独下载 rustc。它装下来的是一组组件,不是一个可执行文件:
装好之后,rustup show 能看到当前默认工具链、已安装的 target。常见的三条命令:
rustup update stable # 升级到最新稳定版
rustup toolchain list # 本机装了哪些工具链
rustup component add clippy rustfmt
stable、beta、nightly 是三条发布通道。stable 每六周发一次,保证不破坏兼容;nightly 每天构建,带实验特性,但可能随时改。业务项目默认用 stable,除非你明确需要某个 nightly 特性,并且能接受它明天变样。
团队协作时,建议在仓库根目录放一个 rust-toolchain.toml,把工具链钉住:
[toolchain]
channel = "1.99.0"
components = ["rustfmt", "clippy"]
放在项目根目录后,进入该目录执行任何 cargo 命令,rustup 会自动切换到这个版本。这解决的是「同事能编译、你编译不过」里最难查的一类:不是代码差异,是编译器版本差异。
从 cargo new 到 cargo run
先建一个项目。注意显式指定 edition:本机 cargo new 在 1.99 下默认生成 2024 edition,而这一系列统一按 2021 讲。
cargo new logstat --bin --edition 2021
生成的结构很小,一个清单文件、一个忽略文件、一个源码文件:
| 路径 | 作用 |
|---|---|
Cargo.toml | 项目清单:包名、版本、edition、依赖 |
.gitignore | 默认忽略 target/ |
src/main.rs | 二进制入口,cargo 默认从这里找 main 函数 |
Cargo.toml 的内容:
[package]
name = "logstat"
version = "0.1.0"
edition = "2021"
[dependencies]
src/main.rs 里是一句 println!("Hello, world!");。在项目目录执行 cargo run,本机输出:
Compiling logstat v0.1.0 (C:\project\logstat)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.52s
Running `target\debug\logstat.exe`
Hello, world!
这四行值得逐行看:Compiling 说明 cargo 调用了 rustc;dev profile 说明用的是开发配置,不优化、带调试信息;target\debug\logstat.exe 是产物路径;最后才是程序输出。项目第一次构建慢,是因为要编译依赖;改一行再跑,通常只编译你改的 crate。
目录里的 target/ 是构建缓存,不该提交到 git;.gitignore 已经帮你写了。整个 target 可以随时删掉,代价是下次全量重编。
Cargo.toml 的每一段
一个稍完整的清单长这样,注释写在各段旁边:
[package]
name = "logstat" # crate 名,也是默认二进制名
version = "0.1.0" # 语义化版本
edition = "2021" # 语法和解析规则,见下一节
rust-version = "1.75" # 最低支持的编译器版本(MSRV)
[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
[dev-dependencies]
tempfile = "3" # 只在测试和示例里可用
[[bin]]
name = "logstat"
path = "src/main.rs"
[profile.release]
opt-level = 3
lto = "thin"
几处容易踩的点。version = "1.0" 不是「精确 1.0」,而是「>=1.0.0, <2.0.0」的兼容范围,Cargo 会在这个范围内选最高可用版本。要精确锁定,得写 =1.0.229;但业务项目通常不需要,锁版本的事交给 Cargo.lock。
[dev-dependencies] 里的依赖只在 cargo test、cargo bench、示例构建时参与编译,不会进最终二进制。[[bin]] 在只有一个 src/main.rs 时可以省略,但项目里既有 lib 又有多个 bin 时,用它显式指定路径最稳。
[profile.release] 控制 --release 构建。lto = "thin" 是折中方案,能减体积、提性能,代价是链接变慢;全量 lto = true 更激进,大项目可能要等很久。
edition 是什么,不是什么
edition 不是版本号,不影响依赖版本。它是一套「语法和语义的约定」,让 Rust 可以在不破坏旧代码的前提下引入新写法。2021 相比 2018 的主要变化包括:闭包捕获更精确(按字段捕获而不是整个结构体)、数组的 IntoIterator 按值迭代、panic! 宏统一、TryFrom/TryInto 进 prelude 等。
几个实际影响:
| 写法 | 2018 行为 | 2021 行为 |
|---|---|---|
for x in [1, 2, 3] | 迭代 &i32 | 按值迭代 i32,数组实现了 IntoIterator |
| 闭包捕获结构体字段 | 可能捕获整个结构体 | 只捕获实际用到的字段,借用范围更小 |
array.into_iter() | 容易拿到引用,需要 .iter() | 默认按值,想借用得写 .iter() |
宏里的 panic! | 格式串规则不统一 | 统一按 format! 的规则解析 |
| 保留字 | — | try 成为保留字,旧代码用 r#try |
本机 1.99 的 cargo 默认给新项目写 2024 edition,这不是错。2024 又改了一批规则(比如 gen 保留字、unsafe 属性、if let 临时值生命周期)。这一系列统一用 2021,是为了资料一致;你新建项目如果用了 2024,遇到报错先确认版本,而不是怀疑代码。
加一个真实依赖:从需求到能跑
需求很具体:读一段 JSON 配置,取出服务名和端口。手写 JSON 解析器不值得,用 serde。在本机项目里执行:
cargo add serde --features derive
cargo add serde_json
真实输出(已去掉颜色控制符和索引更新行):
Adding serde v1.0.229 to dependencies
Features:
+ derive
+ serde_derive
+ std
- alloc
- rc
Adding serde_json v1.0.154 to dependencies
cargo add 会顺手更新 Cargo.toml,并在第一次构建时生成 Cargo.lock。改完的清单是:
[dependencies]
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.154"
代码:
use serde::Deserialize;
#[derive(Deserialize, Debug)]
struct Config {
name: String,
port: u16,
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let text = r#"{"name": "gateway", "port": 8080}"#;
let cfg: Config = serde_json::from_str(text)?;
println!("{}: {}", cfg.name, cfg.port);
Ok(())
}
cargo run 的输出:
Compiling serde v1.0.229
Compiling serde_json v1.0.154
Compiling logstat v0.1.0
Finished `dev` profile [unoptimized + debuginfo] target(s) in 10.25s
Running `target\debug\logstat.exe`
gateway: 8080
这里有三层机制同时工作:#[derive(Deserialize)] 在编译期生成解析代码;features = ["derive"] 打开了 serde 的派生宏支持,不写就找不到 Deserialize 的实现来源;? 把 serde_json::Error 转成 Box<dyn Error>。错误处理下一篇细讲,这里只要知道它能编译。
如果字段改成可选,就在类型上写 Option<String>,serde 默认允许字段缺失为 None。如果字段名和 JSON 不一致,用 #[serde(rename = "listen_port")]。这些是使用细节,不需要现在背。
Cargo.lock 与可复现构建
Cargo.toml 写的是「允许的版本范围」,Cargo.lock 记的是「这次实际用的精确版本和校验和」。两者职责不同:
Cargo.toml
人写的。声明依赖范围和 feature。范围可以宽,表达「兼容哪个大版本」。适合提交到 git,但单独它不能保证两次构建结果一致。
Cargo.lock
cargo 自动生成的。列出每个依赖的精确版本、来源、校验和。保证你、同事、CI 装到完全相同的依赖树。
应用项目(二进制、服务)应该提交 Cargo.lock;库项目可以不提交,让下游自己解析版本。这是官方约定,不是硬规则,但团队最好统一。
升级依赖的常用命令:cargo update 在允许范围内全部升级;cargo update -p serde 只升一个;cargo tree 看完整依赖树;cargo tree -i serde 反查「谁依赖了 serde」。排查「同一个库编进了两个不兼容版本」时,这几个命令比读报错快。
Cargo.lock。它是 cargo 生成的,手工改容易和校验和对不上,下次构建又被覆盖。想锁版本,改 Cargo.toml 的范围,或执行 cargo update --precise。常用命令:什么时候用哪个
| 命令 | 做什么 | 适合的场景 |
|---|---|---|
cargo check | 只做类型检查和借用检查,不生成可执行文件 | 改代码时最频繁用,比 build 快很多 |
cargo build | 编译出 target/debug 产物 | 要跑程序,或检查链接问题 |
cargo run | build 之后运行,可带 -- 传参数 | 开发调试 |
cargo test | 编译并运行单元测试、集成测试 | 改逻辑后验证,配合 -- 过滤用例 |
cargo clippy | 跑一组静态检查,找可疑写法 | 提交前,或 CI 里加 -D warnings |
cargo fmt | 按 rustfmt 规则格式化 | 提交前统一风格 |
cargo build --release | 用 release profile 优化构建 | 压测、发布,不要用它调试 |
cargo doc --open | 生成本地文档并打开浏览器 | 看依赖的 API 签名 |
cargo run -- arg1 arg2 里的 -- 容易漏。不写的话,参数会被 cargo 当成自己的选项解析,结果报 unexpected argument。这是新手最常踩的坑之一。
cargo check 值得养成习惯。它跳过代码生成,只走前端检查,项目越大省的时间越多。但它不检查链接错误,遇到 linker not found 这类问题还是得 build。
workspace:多 crate 项目的组织方式
当项目从一个 bin 长成「lib + 多个 bin + 共用工具库」时,建 workspace 比在一个 crate 里堆 mod 更清晰。根目录的 Cargo.toml 只做两件事:声明成员,统一依赖版本。
[workspace]
members = ["core", "cli", "server"]
resolver = "2"
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
各子 crate 用 serde = { workspace = true } 继承版本,避免三个地方写三个版本号。workspace 的 target/ 是共享的,构建产物集中在一起,磁盘占用更小,也更容易命中缓存。
注意 resolver = "2"(edition 2021 项目的推荐值,2024 默认已是 3):它改变 feature 在构建依赖、目标平台、开发依赖之间的合并方式,能减少「某个依赖被意外打开了不该开的 feature」。老项目没有这一行时,升级 edition 后建议补上。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
linker `link.exe` not found | Windows 上没装 MSVC 构建工具,或环境变量没配好 | 确认装了 Visual Studio Build Tools 的 C++ 组件,再跑 rustup show 看 host target |
error: failed to select a version | 依赖范围互相冲突,或 feature 要求了不存在的版本 | cargo tree -i 包名 找冲突来源,必要时用 cargo update --precise |
unresolved import / 找不到 crate | 依赖没写进 Cargo.toml,或写错了 crate 名 | 先看 Cargo.toml,再确认代码里的 crate 名与 name 一致 |
the trait bound ... is not satisfied | 依赖的 feature 没打开(如 serde 的 derive) | 看依赖文档要求的 feature,在 Cargo.toml 里补上 |
| 本地能编,CI 编不过 | 工具链版本不同,或 Cargo.lock 没提交 | 核对 rust-toolchain.toml 和 Cargo.lock 是否入库 |
cargo run --release 行为和 debug 不同 | 整数溢出在 release 下回绕,debug 下 panic;或优化暴露了 UB | 用 overflow-checks = true 复现,检查 unsafe 代码 |
| 构建越来越慢 | 依赖树膨胀、单态化、没开增量编译或 feature 过多 | cargo tree 数依赖,cargo build --timings 找耗时点 |
edition2024 相关报错 | 新建项目默认 2024,代码按 2021 写 | 看 Cargo.toml 的 edition 字段,按目标版本调整写法 |
边界与代价
Cargo 省掉了 Makefile、依赖下载、版本解析这些手工活,但它不是没有代价。第一,依赖树容易失控。一个看起来很小的库可能拖进几十个 crate,构建时间和体积都跟着涨。cargo tree 应该成为加依赖前的例行检查,而不是出问题才看。
第二,feature 机制是一把双刃剑。它能让同一个 crate 在不同项目里只编译需要的部分,但 feature 组合爆炸也是真实存在的问题——「A 项目开 feature x 能编,B 项目同时开 x 和 y 就编不过」这种情况在生态里出现过。选依赖时优先选 feature 设计克制的库。
第三,构建缓存会占磁盘。target/ 动辄几个 GB,不是异常。可以定期 cargo clean,或者用 cargo-sweep 一类工具清理旧产物。CI 里应该缓存 ~/.cargo 和 target,但要接受缓存失效时的全量重编。
第四,Cargo 的版本解析策略是「选兼容范围内最高版本」。这保证了新项目能拿到更新,但也意味着不加锁的库项目,下游可能装到你没测过的版本。库作者要重视 rust-version 和 CI 的多版本测试。
第五,交叉编译比想象中麻烦。装 target 只是第一步,链接器、系统库、C 依赖都要对应平台的工具链。用 cross 这类工具能简化,但它也要 Docker 或对应 SDK。这部分等你有实际部署需求再深入。
小结
rustup 管工具链,cargo 管项目,Cargo.toml 管声明,Cargo.lock 管锁定。四件事分工清楚,大部分环境问题都能按这个顺序定位。
日常节奏可以很简单:改代码用 cargo check,跑起来用 cargo run,提交前 cargo fmt && cargo clippy && cargo test。别一上来就 --release,也别把 target 提交进仓库。
当天可以自己验证的练习:
- 用
cargo new demo --edition 2021建项目,执行cargo run,再删掉target重跑,比较两次耗时。 cargo add serde --features derive,在main.rs里写一个带#[derive(Deserialize)]的结构体,用serde_json::from_str解析一段固定 JSON。- 执行
cargo tree,数一数 serde + serde_json 一共带进来多少个 crate;再执行cargo tree -i serde看谁依赖它。 - 把
Cargo.toml的edition改成 2024,观察编译报错,再改回来;体会 edition 影响的是语法规则,不是依赖。 - 给项目加
rust-toolchain.toml,把 channel 写成一个低于当前版本的号,执行cargo run,观察 rustup 的下载提示。
下一篇讲所有权、借用与生命周期。项目能跑起来之后,第一段真正会卡住你的代码就是所有权:为什么函数传参之后原变量不能用了、为什么借用检查器在你觉得没问题的地方报错、生命周期标注到底在标什么。这些是 Rust 的地基,绕不过去。