Rust 依赖包管理

文章目录

[1. 两个核心文件](#1. 两个核心文件)
[2. 添加依赖：首选 `cargo add`](#2. 添加依赖：首选 cargo add)
[3. 手动编辑 `Cargo.toml`](#3. 手动编辑 Cargo.toml)
[4. 其他依赖来源](#4. 其他依赖来源)
[5. 构建与更新](#5. 构建与更新)
[6. 总结](#6. 总结)
参考文献

Rust 的依赖管理由 Cargo 负责，它是 Rust 的官方构建系统和包管理器。

核心涉及两个文件：Cargo.toml（依赖声明）和 Cargo.lock（依赖锁定），两者分工明确，共同保证构建的可复现性。

1. 两个核心文件

文件	作用	谁生成	是否提交到 Git
`Cargo.toml`	声明依赖的版本范围、特性、项目元数据	人写	✅ 必须提交
`Cargo.lock`	锁定每个依赖的精确版本和校验和	Cargo 自动生成	✅ 可执行项目必须提交；库项目通常不提交

为什么需要 Cargo.lock？

Cargo.toml 写的是范围（如 serde = "1.0"，表示 1.x 都行）。
Cargo.lock 锁的是精确版本 （如 serde 1.0.200），确保今天和明天构建的依赖完全一致。
没有 Cargo.lock，每次构建可能拉到不同的兼容版本，导致"昨天能编译，今天不能"的问题。

库项目 vs 可执行项目：

项目类型	`Cargo.lock` 是否提交	原因
可执行项目（binary）	✅ 必须提交	保证部署环境与开发环境依赖一致
库项目（library）	❌ 通常不提交	库的使用者会自己生成 lock 文件

2. 添加依赖：首选 `cargo add`

bash 复制代码

# 添加最新兼容版本
cargo add serde

# 添加指定版本
cargo add serde@1.0.200

# 添加并启用特性（features）
cargo add tokio --features full

# 添加开发依赖（仅测试/示例使用）
cargo add --dev criterion

3. 手动编辑 `Cargo.toml`

toml 复制代码

[dependencies]
serde = "1.0"                                        # 语义化版本：允许 1.x.x 最新版
rand = "=0.8.5"                                      # 第二个 = 是版本号的一部分，表示"精确匹配"
reqwest = { version = "0.11", features = ["json"] }  # 带特性

版本号写法 ："1.0" 是默认的插入符（Caret）要求，等价于 >=1.0.0, <2.0.0；对于 0.x 版本，则限制在 >=0.x.0, <0.(x+1).0。

4. 其他依赖来源

toml 复制代码

[dependencies]
# 从 Git 仓库
my_lib = { git = "https://github.com/user/my_lib", branch = "main" }

# 从本地路径（常用于 Workspace 内部）
local_utils = { path = "../local_utils" }

注意：如果要把包发布到 crates.io，仅用 path 声明的依赖是不允许的，需要同时提供 version，例如 { path = "../local_utils", version = "0.1.0" }。

5. 构建与更新

声明依赖后，运行 cargo build 即可。Cargo 会自动下载并编译所有依赖，同时生成 Cargo.lock。

bash 复制代码

cargo build           # 下载并编译依赖
cargo update          # 更新所有依赖到兼容范围内的最新版（修改 Cargo.lock）
cargo update -p serde # 只更新特定依赖
cargo tree            # 查看依赖树
cargo tree -d                              # 只显示重复的依赖
cargo remove serde    # 移除依赖
cargo info serde [--registry <registry>]   # 查看某个依赖 package 的详细信息（版本、依赖、features 等）
cargo search serde [--registry <registry>] # 在 crates.io 上搜索相关 package

（1）关于包版本升级。

升级包版本，具体用哪个命令，取决于你想改的是 Cargo.toml 还是 Cargo.lock。

cargo add：修改 Cargo.toml 里的版本声明。当你想主动把依赖的版本要求提升到更高版本（比如从 0.11 升到 0.12）时使用。

cargo update：修改 Cargo.lock 里的精确版本。它不会动 Cargo.toml，只在现有版本范围内，把锁文件里的版本更新到最新。

所以，如果你是想提升依赖的版本要求，用 cargo add；如果只是想在当前版本约束下刷新锁文件，用 cargo update。

（2）关于包版本查询。

cargo info 用于查看某个 package 的详细信息，不能像 go list -m -versions 命令那样，查出依赖的所有可用版本；

注意：

情况一：在项目目录内执行（且不指定版本）

这时 cargo info 会优先使用你项目 Cargo.lock 中锁定的版本。如果 Cargo.lock 不存在，它才会去查询注册表并自动生成一个新的。所以在这种场景下，它显示的确实是你项目正在使用的版本，而不是 crates.io 上的最新版。

情况二：在项目目录外执行（或指定了版本）

这时 cargo info <包名> 会去查询 crates.io（注册表），显示该包的信息。如果没有指定版本，它会根据你当前 Rust 版本（MSRV）选择一个合适的版本，这个版本通常就是最新稳定版。

cargo search 用于在 registry 搜索 package，默认 registry 是 crates.io。也不能像 go list -m -versions 命令那样，列出依赖包的所有版本，每个命中结果只带一个版本，一般是当前最高的稳定版。

单纯查最新版本号，cargo search 更合适（始终查注册表）；想同时看详细信息，用 cargo info <包名>@latest。

6. 总结

操作	命令 / 写法
添加依赖	`cargo add <crate>`（推荐）
添加带特性的依赖	`cargo add <crate> --features <feat>`
添加开发依赖	`cargo add --dev <crate>`
更新依赖	`cargo update`
查看依赖树	`cargo tree`
依赖声明	`Cargo.toml`（人写，必须提交）
依赖锁定	`Cargo.lock`（自动生成，可执行项目必须提交）

核心记住：Cargo.toml 写声明，Cargo.lock 锁版本 。日常开发用 cargo add 添加依赖，用 cargo build 拉取编译即可。

参考文献

包和crate - Rust 程序设计语言中文版