Cargo.toml

Rust Cargo.toml 一文全解析

在 Rust 生态中，Cargo 是官方提供的构建工具与包管理器，而Cargo.toml 作为 Cargo 的核心配置文件，承载了项目的元信息、依赖管理、编译配置等所有关键信息。无论是简单的单文件项目，还是复杂的多模块工作区，Cargo.toml 都是连接代码与 Cargo 工具链的桥梁。本文将从基础到进阶，结合详细示例，全面拆解 Cargo.toml 的用法，同时拓展相关核心知识点，帮助开发者彻底掌握这一 Rust 项目必备配置文件。

一、Cargo.toml 基础认知

1.1 核心定位与作用

Cargo.toml 采用 TOML（Tom's Obvious, Minimal Language）格式编写，TOML 语法简洁直观，兼顾可读性与机器解析性，相较于 JSON、YAML 更适合作为配置文件。其核心作用包括：

• 定义项目元信息（名称、版本、作者、描述等）；

• 声明项目依赖（第三方库、本地子项目、Git 依赖等）；

• 配置编译规则（优化级别、目标平台、特征开关等）；

• 管理工作区（多 crate 项目的统一协调）。

与之对应的，Cargo 会生成 Cargo.lock 文件（首次构建时自动创建），用于固定依赖的精确版本，确保跨环境构建的一致性。Cargo.toml 是"声明式配置"，Cargo.lock 是"状态快照"，二者协同工作。

1.2 项目初始化后的默认结构

使用 cargo new my_project 初始化一个 Rust 项目后，自动生成的 Cargo.toml 内容如下：

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"  # Rust 版本edition，可选2015、2018、2021

# 可选元信息
authors = ["Your Name <your.email@example.com>"]
description = "A simple Rust project"
license = "MIT"  # 许可证，需对应项目根目录的LICENSE文件
homepage = "https://github.com/your-username/my_project"
repository = "https://github.com/your-username/my_project.git"
documentation = "https://docs.rs/my_project"

[dependencies]
# 此处声明项目依赖，初始为空

其中 [package] 区块是项目元信息的核心，[dependencies] 区块用于声明生产环境依赖，后续会详细展开。

二、核心区块解析：[package]

[package] 区块定义了项目的基础属性，部分字段为必填项，部分为可选项，合理配置可提升项目的规范性与可维护性。

2.1 必填字段

• name ：项目名称，需符合 Rust 标识符规则（仅含字母、数字、下划线，且不以数字开头），同时会作为 crate 名称供其他项目依赖。

  示例：name = "tokio"（知名异步运行时 crate）。

• version ：项目版本，必须遵循 语义化版本（SemVer） 规范，格式为 主版本.次版本.修订号（如 1.2.3）：

• 主版本号：不兼容的 API 变更；

• 次版本号：向后兼容的功能新增；

• 修订号：向后兼容的问题修复。

示例：version = "0.5.0"（表示开发初期的次版本迭代）。

• edition ：指定 Rust 版本 edition，edition 是 Rust 为兼容旧代码、引入新特性而划分的版本通道，目前支持 2015、2018、2021 三个版本，推荐使用最新的 2021。
  注意：edition 决定了编译器的语法规则与标准库特性，例如 2021 edition 支持默认关闭的 async/await 语法优化、更严格的隐私规则等。

2.2 可选字段（推荐配置）

• authors ：作者信息，格式为 姓名 <邮箱>，多个作者用逗号分隔。

示例：authors = ["Alice <alice@example.com>", "Bob <bob@example.com>"]。

• description：项目简短描述（不超过 100 字符），会显示在 crates.io（Rust 官方包仓库）上。

• license ：开源许可证标识（如 MIT、Apache-2.0、GPL-3.0），需与项目根目录的 LICENSE 文件对应，无许可证可设为 license = "UNLICENSED"（闭源）。

• repository/homepage/documentation：分别对应代码仓库、项目主页、文档地址，配置后会在 crates.io 生成跳转链接，提升项目可访问性。

• keywords：项目关键词（数组形式），用于 crates.io 搜索优化。

示例：keywords = ["async", "network", "tokio"]。

• categories：项目分类（数组形式），需从 crates.io 支持的分类列表中选择，便于用户归类查找。

示例：categories = ["asynchronous", "network-programming"]。

三、依赖管理：[dependencies] 及衍生区块

依赖管理是 Cargo.toml 最核心的功能之一，Cargo 支持多种类型的依赖，且能自动解析依赖树、处理版本冲突。依赖声明主要集中在 [dependencies] 区块，同时还有针对特定场景的衍生区块。

3.1 常规依赖声明（生产环境）

在 [dependencies] 下声明的依赖会被包含在生产环境的编译中，常见声明方式有以下几种：

（1）基础版本声明

直接指定 crate 名称和版本，Cargo 会自动拉取符合版本要求的最新版本（并更新到 Cargo.lock）。

[dependencies]
# 精确版本：仅使用 1.5.0 版本
serde = "1.5.0"

# 兼容版本：允许 1.x.x 系列（主版本号不变，次版本和修订号可升级）
tokio = "1.0"  # 等价于 ^1.0.0

# 最小版本：允许 >= 0.4.0 的所有版本（无主版本限制，慎用，可能引入不兼容变更）
reqwest = ">=0.4.0"

# 范围版本：允许 0.3.0 到 0.5.0 之间的版本（不包含 0.5.0）
hyper = "0.3.0 - 0.4.9"

版本前缀说明：Rust 支持语义化版本前缀，常用的有 ^（默认，兼容版本）、~（修订号升级）、*（任意版本），例如：

• ^1.2.3：允许 >=1.2.3 且 <2.0.0；

• ~1.2.3：允许 >=1.2.3 且 <1.3.0；

• *：任意版本（不推荐，版本不可控）。

（2）带特征（Features）的依赖

举例说明： tokio 本身是一个大的 Crate（库）。在这个 Crate 内部，代码是按照功能拆分成不同的 Mod，Rust 的 features 机制 使用了条件编译属性 #[cfg(feature = "...")]

// 只有当启用了 "fs" 这个 feature 时，下面的 mod 才会被编译进最终的库
#[cfg(feature = "fs")]
pub mod fs {
    // 这里是异步文件读写的代码...
    pub async fn read_to_string(...) { ... }
}

如果在 tokio = { version = "1.0", features = ["fs"] } 加了 "fs"：编译器就会把这部分代码编译进去，你就可以 use tokio::fs。这是 按需引入功能，减少编译体积。

特征声明使用 features = ["xxx"]，禁用默认特征用 default-features = false。

[dependencies]
# 启用 tokio 的 "full" 特征（包含所有功能）
tokio = { version = "1.0", features = ["full"] }

# 禁用 reqwest 的默认特征，仅启用 "json" 和 "rustls-tls" 特征
reqwest = { 
  version = "0.11", 
  default-features = false, 
  features = ["json", "rustls-tls"] 
}

# 多特征组合，同时指定版本范围
serde = { version = "1.0", features = ["derive", "rc"] }

拓展：特征（Features）是 Rust 实现条件编译、模块化功能的核心机制，分为"默认特征"（default）和"可选特征"。通过特征可以实现：

• 按需引入依赖（如启用 TLS 支持才依赖 rustls）；

• 区分开发/生产功能（如调试日志特征）；

• 兼容不同版本的依赖（如多版本标准库适配）。

3.2 特殊类型依赖

（1）开发依赖：[dev-dependencies]

仅在开发环境生效的依赖（如测试框架、格式化工具），不会被包含在生产环境的编译产物中。常用于单元测试、集成测试、文档测试等场景。

[dev-dependencies]
# 测试框架
tokio = { version = "1.0", features = ["full", "test-util"] }
assert-json-diff = "2.0"  # JSON 断言工具
rand = "0.8"  # 测试用随机数生成器

# 代码格式化工具（开发辅助）
rustfmt = "1.5"

（2）构建依赖：[build-dependencies]

用于项目构建阶段的依赖（如自定义构建脚本、代码生成工具），构建完成后不会被包含在最终产物中。需配合项目根目录的 build.rs 文件使用。

# 声明构建依赖
[build-dependencies]
cc = "1.0"  # 调用 C 编译器的工具
bindgen = "0.66"  # 生成 Rust 绑定 C 库的工具

# 对应的 build.rs 示例（生成 C 库绑定）
// build.rs
fn main() {
    bindgen::Builder::default()
        .header("src/c_headers/my_lib.h")
        .generate()
        .expect("Failed to generate bindings")
        .write_to_file("src/bindings.rs")
        .expect("Failed to write bindings");
}

（3）本地依赖与 Git 依赖

除了从 crates.io 拉取依赖，还可以声明本地子项目或 Git 仓库中的依赖，适用于开发私有库、定制化第三方库的场景。

[dependencies]
# 本地子项目依赖（路径为相对路径，指向子 crate）
my_utils = { path = "./my_utils" }  # 同级目录下的 my_utils 子项目

# Git 仓库依赖（默认拉取 main 分支最新提交）
tokio = { git = "https://github.com/tokio-rs/tokio.git" }

# 指定 Git 分支、标签或提交哈希
my_crate = { 
  git = "https://github.com/your-username/my_crate.git", 
  branch = "dev",  # 分支
  tag = "v0.3.0",  # 标签（优先级高于 branch）
  rev = "a1b2c3d"  # 提交哈希（精确到特定版本）
}

# Git 依赖 + 特征启用
reqwest = { 
  git = "https://github.com/seanmonstar/reqwest.git", 
  rev = "v0.11.18", 
  features = ["json"] 
}

注意：本地依赖的子项目也必须是 Rust 项目（包含自身的 Cargo.toml），Cargo 会自动编译子项目并关联依赖。

3.3 依赖解析与冲突处理

Cargo 会自动解析所有依赖的版本需求，生成一棵依赖树，并在 Cargo.lock中固定每个依赖的精确版本。当出现版本冲突时（如 A 依赖 1.0 版本的 C，B 依赖 2.0 版本的 C），Cargo 会尝试以下策略解决：

1. 优先选择符合所有依赖项版本范围的版本；

2. 若无法找到兼容版本，会报错并提示冲突的依赖链，此时需手动调整依赖版本，或通过 resolver 字段指定解析策略。

示例：指定依赖解析器版本（解决复杂依赖冲突）：

[package]
# ... 其他配置
resolver = "2"  # 启用新版解析器（Rust 1.51+ 支持），优化多版本依赖冲突处理

拓展：Cargo 1.51 引入的 2 版解析器，支持"同一 crate 多版本共存"（如同时依赖 1.0 和 2.0 版本的 serde），避免了旧版解析器的"版本强制统一"问题，更适合复杂项目。

四、进阶配置：编译、工作区与自定义设置

除了基础元信息和依赖管理，Cargo.toml 还支持丰富的进阶配置，可自定义编译规则、管理多 crate 工作区、配置目标平台等。

4.1 编译配置：[profile]

[profile] 区块用于配置不同编译模式的优化级别、调试信息、警告规则等，Cargo 默认提供 4 种编译模式，也支持自定义模式。

# 开发模式（默认，cargo build 启用）
[profile.dev]
opt-level = 0  # 优化级别（0-3，0 表示无优化，编译快，适合调试）
debug = true   # 生成调试信息（便于 gdb/lldb 调试）
rpath = false  # 不使用 rpath 加载动态库
warn = true    # 启用所有警告

# 发布模式（cargo build --release 启用）
[profile.release]
opt-level = 3  # 最高优化级别（编译慢，运行快）
debug = false  # 关闭调试信息（减小产物体积）
strip = true   # 剥离符号表（进一步减小体积）
lto = "thin"   # 启用轻量级链接时优化（LTO），提升运行效率

# 测试模式（cargo test 启用，继承 dev 模式配置）
[profile.test]
opt-level = 1  # 适度优化（平衡测试速度与运行速度）
debug = true

# 文档测试模式（cargo test --doc 启用）
[profile.doc]
opt-level = 2

拓展：优化级别 opt-level 详解：

• 0：无优化，编译速度最快，适合开发调试；

• 1：基础优化，平衡编译速度与运行速度；

• 2：全面优化，适合大多数生产场景；

• 3：最高级优化（如循环展开、函数内联），编译时间长，适合对性能要求极高的场景；

• s/z：以减小产物体积为目标的优化（s 优先体积，z 极致体积）。

4.2 工作区配置：[workspace]

当项目包含多个 crate 时，可通过 [workspace] 配置工作区，实现多 crate 的统一依赖管理、编译和测试。工作区的 Cargo.toml 通常位于项目根目录，子 crate 位于子目录中。以下是简单且贴近实际开发的代码实例：

1. 项目目录结构（核心层级）

# 根目录（工作区根）
my_workspace/
├── Cargo.toml  # 工作区配置文件（根配置）
├── crates/     # 子crate存放目录
│   ├── core/   # 核心功能子crate
│   │   ├── Cargo.toml
│   │   └── src/
│   └── cli/    # 命令行工具子crate
│       ├── Cargo.toml
│       └── src/
└── examples/   # 示例代码（可选子项目）
    └── demo/
        ├── Cargo.toml
        └── src/

2. 工作区根目录 Cargo.toml（核心配置）

[workspace]
# 声明工作区包含的子crate（路径对应目录结构）
members = [
  "crates/core",   # 核心子crate
  "crates/cli",    # 命令行子crate
  "examples/demo"  # 示例子项目（可选）
]

# 工作区共享依赖（所有子crate可直接继承，无需重复写版本）
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }  # 序列化工具
thiserror = "1.0"  # 错误处理工具

3. 子crate配置（以 crates/core 为例）

[package]
name = "core"  # 子crate名称
version = "0.1.0"
edition = "2021"

# 依赖声明：直接继承工作区共享依赖，无需重复指定版本
[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }

# 子crate专属依赖（仅本crate使用，不共享）
rand = "0.8"  # 随机数工具

4. 子crate配置（以 crates/cli 为例）

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

[dependencies]
# 继承工作区依赖
serde = { workspace = true }
thiserror = { workspace = true }

# 依赖同工作区的core子crate（本地依赖）
core = { path = "../core" }  # 相对路径指向同级core目录

通过以上配置，在工作区根目录执行 cargo build 可一次性编译所有子crate，共享依赖版本统一，子crate间可通过路径依赖关联，实现多crate协同管理。

# 根目录 Cargo.toml（工作区配置）
[workspace]
# 声明子 crate（路径匹配，支持通配符）
members = [
  "crates/core",    # 核心功能 crate
  "crates/api",     # API 层 crate
  "crates/cli",     # 命令行工具 crate
  "examples/*"      # 所有示例项目
]

# 工作区共享依赖（子 crate 可直接继承，无需重复声明）
[workspace.dependencies]
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
thiserror = "1.0"  # 错误处理 crate

# 子 crate（crates/core/Cargo.toml）示例
[package]
name = "core"
version = "0.1.0"
edition = "2021"

[dependencies]
# 继承工作区依赖（无需指定版本）
tokio = { workspace = true }
serde = { workspace = true }
thiserror = { workspace = true }

# 子 crate 专属依赖
rand = "0.8"

工作区优势：

• 统一依赖版本，避免子 crate 间依赖冲突；

• 单次编译所有子 crate，提升构建效率；

• 共享开发依赖、编译配置，减少重复代码。

4.3 目标平台配置：[target]

针对不同目标平台（如 x86_64、ARM、WebAssembly）配置专属依赖或编译规则，实现跨平台适配。

# 为 Windows 平台配置专属依赖
[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3", features = ["winbase"] }  # Windows API 绑定

# 为 Linux 平台配置专属依赖
[target.'cfg(unix)'.dependencies]
libc = "0.2"  # Linux C 标准库绑定

# 为 WebAssembly 平台配置编译规则
[target.wasm32-unknown-unknown]
rustflags = ["--no-standard-libraries"]  # 禁用标准库（Wasm 轻量场景）

# 针对特定架构配置优化
[target.x86_64-unknown-linux-gnu.profile.release]
opt-level = 3
lto = true

拓展：目标平台标识格式为 target.<目标三元组> 或 target.'cfg(条件)'，常见目标三元组：

• x86_64-unknown-linux-gnu：64 位 Linux（GNU 工具链）；

• x86_64-pc-windows-msvc：64 位 Windows（MSVC 工具链）；

• wasm32-unknown-unknown：WebAssembly（无操作系统）；

• aarch64-apple-darwin：64 位 macOS（ARM 架构）。

4.4 其他实用配置

（1）自定义构建脚本

通过 build 字段指定自定义构建脚本（默认是 build.rs），脚本会在项目编译前执行，可用于代码生成、依赖检查、环境变量设置等。

[package]
# ... 其他配置
build = "build_scripts/main.rs"  # 自定义构建脚本路径

# 构建脚本中设置的环境变量，可在代码中使用
[env]
MY_PROJECT_VERSION = { value = "$CARGO_PKG_VERSION", force = true }

（2）文档配置

配置项目文档的生成规则，提升文档可读性。

[package]
# ... 其他配置
documentation = "https://docs.rs/my_project"
readme = "README.md"  # 指定文档首页（会嵌入到 crates.io 页面）
exclude = ["docs/*", "tests/*"]  # 生成文档时排除的文件

[doc]
html_logo = "assets/logo.png"  # 文档首页 Logo
html_favicon = "assets/favicon.ico"  # 文档浏览器图标
warn_doc_markdown = true  # 警告文档中的 Markdown 语法错误

五、实战案例：完整的 Cargo.toml 配置

以下是一个异步 HTTP 服务项目的完整 Cargo.toml 配置，整合了前文讲解的核心知识点，可直接作为项目模板参考。

# 实战案例：异步HTTP服务项目完整Cargo.toml配置
# 整合元信息、依赖管理、编译配置、跨平台适配等核心功能，可直接作为项目模板

# -------------------------- 项目核心元信息配置 --------------------------
[package]
# 项目名称（需符合Rust标识符规则，将作为二进制文件/库名称）
name = "async-http-server"
# 项目版本（遵循语义化版本：主版本.次版本.修订号）
version = "0.1.0"
# 指定Rust编译版本（推荐2021，支持最新语法特性与标准库优化）
edition = "2021"
# 作者信息（格式：姓名<邮箱>，多个作者用逗号分隔）
authors = ["John Doe <john@example.com>"]
# 项目描述（≤100字符，将展示在crates.io仓库页面）
description = "A simple asynchronous HTTP server with Rust and Tokio"
# 开源许可证（此处为MIT，需在项目根目录放置对应LICENSE文件）
license = "MIT"
# 代码仓库地址（Git仓库URL，便于他人贡献与查看源码）
repository = "https://github.com/johndoe/async-http-server.git"
# 项目主页（可与仓库地址一致，或指向项目文档站点）
homepage = "https://github.com/johndoe/async-http-server"
# 关键词（数组形式，用于crates.io搜索优化，贴合项目核心功能）
keywords = ["async", "http", "tokio", "server"]
# 项目分类（从crates.io支持列表选择，便于用户归类查找）
categories = ["asynchronous", "web-programming"]
# 启用新版依赖解析器（Rust 1.51+支持，优化多版本依赖冲突，支持同 crate 多版本共存）
resolver = "2"

# -------------------------- 工作区配置 --------------------------
[workspace]
# 声明工作区包含的子crate（此处仅包含示例项目，可扩展多个业务子crate）
members = ["examples/demo-server"]

# -------------------------- 工作区共享依赖 --------------------------
# 所有子crate可通过workspace = true继承，无需重复声明版本，统一依赖管理
[workspace.dependencies]
# Tokio异步运行时（启用full特征，包含所有异步功能如网络、定时器等）
tokio = { version = "1.0", features = ["full"] }
# Axum异步HTTP框架（用于快速开发HTTP服务，适配Tokio运行时）
axum = "0.7"
# Serde序列化/反序列化库（启用derive特征，支持自动生成序列化代码）
serde = { version = "1.0", features = ["derive"] }
# Thiserror错误处理库（简化自定义错误类型的定义）
thiserror = "1.0"
# Tracing日志框架（用于异步场景下的结构化日志记录）
tracing = "0.1"
# Tracing订阅器（用于日志的收集、过滤与输出）
tracing-subscriber = "0.3"

# -------------------------- 生产环境依赖 --------------------------
[dependencies]
# 继承工作区共享依赖，减少重复配置，保证版本统一
tokio = { workspace = true }
axum = { workspace = true }
serde = { workspace = true }
thiserror = { workspace = true }
tracing = { workspace = true }
tracing-subscriber = { workspace = true }

# -------------------------- 平台专属依赖 --------------------------
# Windows系统专属依赖（条件编译，仅在Windows环境下生效）
[target.'cfg(windows)'.dependencies]
# WinAPI绑定库（启用winbase和processenv特征，用于Windows系统API调用）
winapi = { version = "0.3", features = ["winbase", "processenv"] }

# Unix类系统专属依赖（Linux/macOS等，仅在Unix环境下生效）
[target.'cfg(unix)'.dependencies]
# Libc库（用于调用Unix系统C标准库接口）
libc = "0.2"

# -------------------------- 开发环境依赖 --------------------------
# 仅在开发/测试时生效，不包含在生产环境编译产物中
[dev-dependencies]
# 断言匹配工具（用于单元测试中精准匹配结果）
assert_matches = "0.1.10"
# Tokio测试工具（适配异步测试场景，简化异步测试用例编写）
tokio-test = "0.4"
# 随机数生成库（用于测试场景中生成模拟数据）
rand = "0.8"

# -------------------------- 构建依赖 --------------------------
# 仅在项目构建阶段生效，构建完成后不参与最终产物
[build-dependencies]
# CC工具（用于调用系统C编译器，适配需编译C代码的场景）
cc = "1.0"

# -------------------------- 编译配置（开发模式） --------------------------
# cargo build默认启用，侧重编译速度，便于开发调试
[profile.dev]
opt-level = 0  # 优化级别0（无优化，编译最快，保留调试信息）
debug = true   # 生成调试信息（支持gdb/lldb调试工具）
warn = true    # 启用所有编译警告，提前规避潜在问题

# -------------------------- 编译配置（发布模式） --------------------------
# cargo build --release启用，侧重运行性能与产物体积
[profile.release]
opt-level = 3  # 优化级别3（最高级优化，运行最快，编译耗时最长）
debug = false  # 关闭调试信息（减小产物体积）
strip = true   # 剥离符号表（进一步压缩产物体积）
lto = "thin"   # 启用轻量级链接时优化（提升运行效率，平衡编译速度）
codegen-units = 1  # 减少代码生成单元（提升优化效果，代价是编译时间增加）

# -------------------------- 文档生成配置 --------------------------
[doc]
html_logo = "assets/logo.png"  # 文档首页Logo（提升文档美观度）
html_favicon = "assets/favicon.ico"  # 文档浏览器图标（自定义文档标识）

六、拓展知识点与最佳实践

6.1 Cargo.toml 与 Cargo.lock 的关系

• Cargo.toml：声明依赖的版本范围、特征等"意图"，是项目的源配置；

• Cargo.lock：记录依赖的精确版本、依赖树结构，是构建的"状态快照"。

最佳实践：

• 库项目（发布到 crates.io）：不提交 Cargo.lock，让使用者根据自身依赖树选择版本；

• 二进制项目（如服务、工具）：提交 Cargo.lock，确保所有环境构建版本一致，避免意外更新。

6.2 依赖版本管理最佳实践

1. 遵循语义化版本规范，避免使用 *、^0.0.x 等不稳定版本范围；

2. 定期更新依赖（使用 cargo update），修复安全漏洞，但需注意主版本更新可能带来的不兼容变更；

3. 使用 cargo audit 工具检查依赖的安全漏洞（需提前安装：cargo install cargo-audit）；

4. 复杂项目使用工作区统一管理依赖版本，减少重复声明和冲突。

6.3 常见问题排查

（1）依赖冲突报错

报错示例：version solving failed: package A v1.0.0 depends on B ^0.1.0, but B v0.2.0 is required by C v2.0.0。

解决方法：

• 升级/降级冲突的依赖，使其版本范围兼容；

• 启用新版依赖解析器（resolver = "2"），允许同一 crate 多版本共存；

• 手动指定冲突依赖的版本，在 [dependencies] 中强制声明兼容版本。

（2）构建脚本执行失败

排查步骤：

• 检查 build.rs 语法是否正确，依赖是否安装完整；

• 通过 cargo build -vv 查看详细构建日志，定位报错原因；

• 确认构建依赖版本与 Rust 版本兼容。

（3）特征启用后功能未生效

解决方法：

• 检查特征名称是否正确（区分大小写，参考 crate 文档）；

• 确认是否禁用了默认特征（default-features = false）导致依赖缺失；

• 执行 cargo clean 清理缓存后重新构建，避免旧编译产物干扰。

七、总结

Cargo.toml 作为 Rust 项目的"灵魂配置文件"，不仅承担着元信息声明、依赖管理的基础功能，还通过进阶配置支撑起复杂项目的编译优化、跨平台适配、多 crate 协同等核心需求。掌握其用法，能大幅提升 Rust 项目的开发效率、可维护性和性能。

本文从基础到进阶，覆盖了 Cargo.toml 的核心区块、依赖管理技巧、进阶配置场景，并结合实战案例和最佳实践，帮助开发者全面掌握其用法。在实际开发中，需根据项目类型（库/二进制、单 crate/多 crate）灵活调整配置，同时善用 Cargo 工具链（如 cargo update、cargo audit、cargo doc）提升开发体验。