接手一个 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。它装下来的是一组组件,不是一个可执行文件:

rustc编译器本体。把 .rs 文件编译成目标平台的机器码,负责类型检查和借用检查。
cargo项目与依赖管理器。调 rustc、下载 crate、跑测试、生成文档,日常几乎只用它。
rust-std目标平台的标准库。交叉编译时经常需要额外装别的 target。
rustfmt / clippy格式化和静态检查工具,按需安装,不算核心。

装好之后,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,遇到报错先确认版本,而不是怀疑代码。

edition 是每个 crate 自己声明的,同一个 workspace 里可以并存 2021 和 2024。依赖用哪个 edition 由它自己的 Cargo.toml 决定,不影响你。

加一个真实依赖:从需求到能跑

需求很具体:读一段 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 runbuild 之后运行,可带 -- 传参数开发调试
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 foundWindows 上没装 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 提交进仓库。

当天可以自己验证的练习:

  1. 用 cargo new demo --edition 2021 建项目,执行 cargo run,再删掉 target 重跑,比较两次耗时。
  2. cargo add serde --features derive,在 main.rs 里写一个带 #[derive(Deserialize)] 的结构体,用 serde_json::from_str 解析一段固定 JSON。
  3. 执行 cargo tree,数一数 serde + serde_json 一共带进来多少个 crate;再执行 cargo tree -i serde 看谁依赖它。
  4. 把 Cargo.toml 的 edition 改成 2024,观察编译报错,再改回来;体会 edition 影响的是语法规则,不是依赖。
  5. 给项目加 rust-toolchain.toml,把 channel 写成一个低于当前版本的号,执行 cargo run,观察 rustup 的下载提示。

下一篇讲所有权、借用与生命周期。项目能跑起来之后,第一段真正会卡住你的代码就是所有权:为什么函数传参之后原变量不能用了、为什么借用检查器在你觉得没问题的地方报错、生命周期标注到底在标什么。这些是 Rust 的地基,绕不过去。