[dependencies] 依赖
核心概念
[dependencies] 是 Cargo.toml 中声明项目运行时依赖的段。这里列出的所有 crate 会在编译时被下载、编译,并链接到最终的二进制文件中。依赖声明的基本格式是 crate_name = "version",也可以用更详细的表格语法来指定 features、路径、git 源等。
Cargo 从 crates.io(默认注册中心)下载依赖,也支持从本地路径、Git 仓库、自定义注册中心获取。依赖版本使用语义化版本(SemVer)规范,Cargo 会自动解析依赖树,选择满足所有约束的兼容版本。
[dependencies]
# 简写格式:只指定版本
rand = "0.8"
log = "0.4"
# 表格格式:指定更多选项
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
# 路径依赖
my-utils = { path = "../my-utils" }
# Git 依赖
my-lib = { git = "https://github.com/user/my-lib" }
# 可选依赖
openssl = { version = "0.10", optional = true }
# 重命名
old_serde = { package = "serde", version = "0.9" }版本指定方式
[dependencies]
# 脱字符(^):默认方式,兼容更新
# "0.8" 等同于 "^0.8" 等同于 ">=0.8.0, <0.9.0"
rand = "0.8"
rand_exact = "0.8.5" # >=0.8.5, <0.9.0
# 波浪号(~):只允许 patch 级别更新
serde = "~1.0.100" # >=1.0.100, <1.1.0
# 通配符(*)
log = "0.4.*" # >=0.4.0, <0.5.0
# 精确版本
uuid = "=1.6.1" # 只允许 1.6.1
# 范围
num = ">=1.0, <2.0"
# 大于等于
bytes = ">=1.5"| 写法 | 含义 | 示例 |
|---|---|---|
"1.2.3" / "^1.2.3" | >=1.2.3, <2.0.0 | 兼容更新 |
"~1.2.3" | >=1.2.3, <1.3.0 | 只允许 patch |
"0.2.3" / "^0.2.3" | >=0.2.3, <0.3.0 | 0.x 更严格 |
"0.0.3" / "^0.0.3" | >=0.0.3, <0.0.4 | 0.0.x 精确 |
"=1.2.3" | 精确 1.2.3 | 锁定版本 |
"*" | 任何版本 | 不推荐 |
">=1, <2" | 范围指定 | 自定义范围 |
依赖选项
[dependencies]
# version:版本要求
serde = { version = "1.0" }
# features:启用指定的 feature
serde = { version = "1.0", features = ["derive", "rc"] }
# default-features:是否启用默认 feature
tokio = { version = "1", default-features = false, features = ["rt", "macros"] }
# optional:可选依赖(用于 feature 系统)
openssl = { version = "0.10", optional = true }
# package:使用不同的包名(重命名)
serde1 = { package = "serde", version = "1.0" }
# registry:从指定的注册中心获取
my-crate = { version = "0.1", registry = "my-registry" }基本示例
# 一个 Web 项目的典型依赖配置
[package]
name = "web-api"
version = "0.1.0"
edition = "2024"
[dependencies]
# Web 框架
axum = "0.7"
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "trace", "compression-gzip"] }
# 异步运行时
tokio = { version = "1", features = ["full"] }
# 序列化
serde = { version = "1", features = ["derive"] }
serde_json = "1"
# 数据库
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres", "chrono", "uuid"] }
# 日志
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
# 工具
anyhow = "1"
chrono = { version = "0.4", features = ["serde"] }
uuid = { version = "1", features = ["v4", "serde"] }
dotenvy = "0.15"// 在 Rust 代码中使用这些依赖
use axum::{Router, routing::get};
use serde::{Serialize, Deserialize};
use tokio;
#[derive(Serialize, Deserialize, Debug)]
struct User {
name: String,
age: u32,
}
async fn hello() -> &'static str {
"Hello, World!"
}
#[tokio::main]
async fn main() {
let app = Router::new().route("/", get(hello));
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
println!("服务器启动在 http://localhost:3000");
axum::serve(listener, app).await.unwrap();
}常见问题
问题一:依赖名中的 - 和 _ 怎么处理?
Cargo.toml 中用 - 或 _ 都行(如 serde-json 和 serde_json),但代码中 use 导入时必须用 _。Cargo 在解析时会将 - 视为 _。
问题二:怎么查看项目的完整依赖树?
运行 cargo tree 查看依赖树。用 cargo tree -d 查看重复依赖,cargo tree -i some_crate 查看某个 crate 被谁依赖。
问题三:多个依赖要求同一个 crate 的不同版本怎么办?
Cargo 会尝试选择满足所有约束的版本。如果无法兼容(如 0.x 和 1.x),Cargo 会同时编译两个版本,但这可能导致类型不兼容。
问题四:怎么更新依赖版本?
cargo update 在 Cargo.lock 的版本范围内更新到最新版。如果要升级到新的大版本,需要手动修改 Cargo.toml 中的版本号。
适用场景
- 添加第三方库:从 crates.io 引入功能库
- 版本控制:通过语义化版本约束依赖更新范围
- Feature 选择:只启用需要的功能以减小编译产物
- 依赖重命名:同时使用一个 crate 的多个版本
注意事项
"0.x"版本的兼容范围比"1.x"小得多optional = true的依赖默认不编译,需要通过 feature 启用default-features = false可以禁用默认 feature- 依赖版本范围不宜过宽(如
"*"),影响可重复构建 - 使用
cargo update更新 Cargo.lock 中的精确版本 - 库项目通常不提交 Cargo.lock,应用项目应该提交
总结
[dependencies] 段声明项目的运行时依赖。版本使用语义化版本规范,默认的脱字符写法 "1.0" 表示兼容更新(>=1.0.0, <2.0.0)。依赖可以指定 features、禁用默认 features、标记为可选、从路径或 Git 获取、甚至重命名。Cargo 自动解析依赖树并选择兼容版本。cargo tree 查看依赖关系,cargo update 在约束范围内更新版本。0.x 版本的兼容范围更严格,"0.2" 只兼容 0.2.x 而非所有 0.x。