[dependencies] 依赖 ​

核心概念 ​

[dependencies] 是 Cargo.toml 中声明项目运行时依赖的段。这里列出的所有 crate 会在编译时被下载、编译,并链接到最终的二进制文件中。依赖声明的基本格式是 crate_name = "version",也可以用更详细的表格语法来指定 features、路径、git 源等。

Cargo 从 crates.io(默认注册中心)下载依赖,也支持从本地路径、Git 仓库、自定义注册中心获取。依赖版本使用语义化版本(SemVer)规范,Cargo 会自动解析依赖树,选择满足所有约束的兼容版本。

toml
[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" }

版本指定方式 ​

toml
[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.00.x 更严格
"0.0.3" / "^0.0.3">=0.0.3, <0.0.40.0.x 精确
"=1.2.3"精确 1.2.3锁定版本
"*"任何版本不推荐
">=1, <2"范围指定自定义范围

依赖选项 ​

toml
[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" }

基本示例 ​

toml
# 一个 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
// 在 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。