Rust Cargo：包管理与依赖配置

Rust 的官方构建工具和包管理器叫 Cargo。它不仅能编译项目、运行测试，还能自动下载、编译和链接你项目所需的第三方代码（称为“依赖”）。掌握 Cargo 的依赖配置方法，是高效开发 Rust 项目的必备技能。

创建新项目并理解目录结构

执行 cargo new my_project 命令创建一个名为 my_project 的新项目。

该命令会生成如下关键文件和目录：

• Cargo.toml：项目的配置文件，所有依赖和元数据都在这里声明。
• src/main.rs：主程序入口（如果是库项目，则是 src/lib.rs）。
• target/：编译产物存放目录（通常不提交到版本控制）。

打开 Cargo.toml 文件，你会看到类似以下内容：

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"

[dependencies]

其中 [dependencies] 下方就是你添加外部库的地方。

添加公开依赖（来自 crates.io）

crates.io 是 Rust 官方的开源包仓库。绝大多数常用库都托管于此。

编辑 Cargo.toml 文件，在 [dependencies] 下添加一行，格式为 库名 = "版本号"。

例如，要使用 rand 库（用于生成随机数），写入：

[dependencies]
rand = "0.8"

这表示允许使用 0.8.x 系列的最新兼容版本（语义化版本规则）。

保存文件后，运行 cargo build 或 cargo run。Cargo 会自动：

1. 检查 Cargo.lock（若存在）或从 crates.io 获取 rand 及其依赖。
2. 下载并编译所有缺失的依赖。
3. 更新 Cargo.lock 锁定确切版本。

此后每次构建都会使用锁定的版本，确保团队成员环境一致。

指定更精确的版本要求

除了 "0.8" 这种简写，你还可以用更明确的方式控制版本：

注意：除非有特殊需求，一般推荐使用 "x.y" 形式，让 Cargo 自动处理兼容性。

使用 Git 仓库作为依赖

有时你需要使用尚未发布到 crates.io 的库，或使用某个分支/提交的代码。

在 Cargo.toml 中这样写：

[dependencies]
my_util = { git = "https://github.com/user/my_util.git", branch = "dev" }

可选参数包括：

• branch = "分支名"
• tag = "标签名"
• rev = "具体提交哈希"

例如，指定某次提交：

[dependencies]
cool_lib = { git = "https://github.com/example/cool.git", rev = "a1b2c3d" }

注意：Git 依赖不会写入 Cargo.lock 的版本号，而是记录完整 URL 和 commit hash，确保可重现。

引用本地路径依赖

当你同时开发多个关联项目（如核心库 + 应用），可以用本地路径避免反复发布。

假设你的目录结构如下：

/workspace
  ├── app/
  └── my_core_lib/

在 app/Cargo.toml 中添加：

[dependencies]
my_core_lib = { path = "../my_core_lib" }

这样，app 就能直接使用 my_core_lib 的最新代码，无需发布或推送。

提示：path 是相对于当前 Cargo.toml 文件的路径。

开发依赖（仅用于测试或构建）

有些依赖只在开发时需要，比如测试框架、代码生成器等。把它们放在 [dev-dependencies] 下，避免污染生产环境。

编辑 Cargo.toml：

[dev-dependencies]
pretty_assertions = "1.0"

这样，pretty_assertions 只会在运行 cargo test 时被编译和链接，不会包含在最终发布的二进制中。

类似地，还有 [build-dependencies]，用于自定义构建脚本（build.rs）所需的依赖。

查看和更新依赖

运行 cargo tree 可以查看当前项目的完整依赖树，包括版本和来源。

示例输出片段：

my_project v0.1.0
├── rand v0.8.5
│   ├── rand_chacha v0.3.1
│   └── rand_core v0.6.4
└── serde v1.0.197

要升级依赖，先修改 Cargo.toml 中的版本要求（如从 "0.8" 改为 "0.9"），然后执行 cargo update -p rand。这会更新 Cargo.lock 并重新解析依赖。

如果想升级所有依赖到最新兼容版本，运行 cargo update（不带参数）。

特性（Features）控制依赖功能

很多库提供“特性”（features），允许你按需启用部分功能，减少编译时间和二进制体积。

例如，serde 默认不包含对 JSON 的支持，需要显式开启 derive 和 json 特性。

在 Cargo.toml 中这样写：

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

你也可以为自己的项目定义特性，并条件性地启用依赖：

[features]
default = ["network"]
network = ["reqwest"]
database = ["sqlx"]

[dependencies]
reqwest = { version = "0.11", optional = true }
sqlx = { version = "0.7", optional = true, features = ["runtime-tokio-rustls"] }

用户可通过 --features database 编译时启用数据库支持。

解决依赖冲突

当两个依赖要求同一库的不同不兼容版本时，Cargo 会报错。

解决方法：

1. 检查是否可以通过升级其中一个依赖来统一版本。
2. 查看该库的 changelog，确认能否安全降级或升级。
3. 使用 [patch] 覆盖特定依赖的来源（高级用法）。

例如，强制将某个间接依赖替换为 Git 版本：

[patch.crates-io]
problematic_lib = { git = "https://github.com/fork/problematic.git", rev = "fix" }

这会告诉 Cargo：凡是在 crates.io 上解析到的 problematic_lib，一律用这个 Git 提交替代。

发布你的库到 crates.io

当你写好一个可复用的库，可以发布给他人使用。

确保 Cargo.toml 中有完整信息：

[package]
name = "your_crate_name"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
edition = "2021"
description = "A short description"
license = "MIT"
repository = "https://github.com/you/your_crate"

登录 crates.io（首次需注册）：

cargo login abcdef12345...  # 替换为你的 API token

执行 cargo publish 即可发布。

注意：发布前建议先运行 cargo publish --dry-run 预演。