Cargo.toml 配置 #

文件概述 #

Cargo.toml 是 Cargo 项目的配置文件，使用 TOML 格式编写。它定义了项目的元数据、依赖关系、编译配置等信息。

基本结构 #

toml

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

[dependencies]
serde = "1.0"

[dev-dependencies]
tokio = { version = "1.0", features = ["full"] }

[build-dependencies]
cc = "1.0"

[features]
default = ["feature1"]
feature1 = []

[profile.release]
opt-level = 3

[package] 部分 #

[package] 部分定义了项目的基本信息。

必需字段 #

name #

项目名称，用于标识项目。

toml

[package]
name = "my_awesome_project"

命名规则：

只能包含字母、数字、下划线和连字符
必须以字母开头
不能使用 Rust 关键字
建议使用 snake_case 或 kebab-case

version #

项目版本号，遵循语义化版本规范。

toml

[package]
version = "0.1.0"
version = "1.0.0"
version = "2.1.3-alpha.1"

版本格式：MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

edition #

Rust 版本（edition），指定使用的 Rust 语言特性集。

toml

[package]
edition = "2021"    # 推荐，最新稳定版
edition = "2018"    # 较旧项目
edition = "2015"    # 最初版本

Edition	发布年份	主要特性
2015	2015	基础 Rust
2018	2018	模块系统改进、错误处理增强
2021	2021	闭包改进、数组 IntoIterator、默认 panic 行为

可选字段 #

description #

项目描述。

toml

[package]
description = "A fast and secure web framework"

documentation #

文档 URL。

toml

[package]
documentation = "https://docs.rs/my_project"

readme #

README 文件路径。

toml

[package]
readme = "README.md"
readme = "docs/README.md"

homepage #

项目主页 URL。

toml

[package]
homepage = "https://myproject.com"

repository #

代码仓库 URL。

toml

[package]
repository = "https://github.com/user/my_project"

license 和 license-file #

许可证信息。

toml

# 使用 SPDX 标识符
[package]
license = "MIT"
license = "Apache-2.0"
license = "MIT OR Apache-2.0"

# 或指定许可证文件
license-file = "LICENSE"

keywords #

关键词，用于 crates.io 搜索。

toml

[package]
keywords = ["web", "framework", "async"]

categories #

分类，用于 crates.io 分类。

toml

[package]
categories = ["web-programming", "asynchronous"]

可用分类参考：https://crates.io/category_slugs

authors #

作者列表。

toml

[package]
authors = ["John Doe <john@example.com>", "Jane Doe <jane@example.com>"]

exclude 和 include #

控制发布时包含/排除的文件。

toml

[package]
exclude = [
    "docs/*",
    "tests/*",
    "*.bak",
    "*.tmp",
]

include = [
    "src/**/*",
    "Cargo.toml",
    "README.md",
    "LICENSE",
]

publish #

发布配置。

toml

# 禁止发布
[package]
publish = false

# 发布到特定注册表
publish = ["my-registry"]

# 默认发布到 crates.io
publish = true

metadata #

自定义元数据。

toml

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

[package.metadata.playground]
features = ["full"]

完整示例 #

toml

[package]
name = "my_awesome_project"
version = "0.1.0"
edition = "2021"
rust-version = "1.70"
description = "A fast and secure web framework"
documentation = "https://docs.rs/my_awesome_project"
readme = "README.md"
homepage = "https://myproject.com"
repository = "https://github.com/user/my_awesome_project"
license = "MIT OR Apache-2.0"
keywords = ["web", "framework", "async"]
categories = ["web-programming", "asynchronous"]
authors = ["John Doe <john@example.com>"]
exclude = ["docs/*", "tests/*"]
publish = true

[dependencies] 部分 #

[dependencies] 定义项目运行时依赖。

基本语法 #

toml

[dependencies]
serde = "1.0"
tokio = "1.0"

版本指定方式 #

toml

[dependencies]
# 语义化版本范围
serde = "1.0"           # ^1.0.0，兼容更新
serde = "^1.0"          # 同上
serde = "~1.0"          # 1.0.*，补丁更新
serde = ">=1.0.0"       # 大于等于
serde = "<2.0.0"        # 小于
serde = ">=1.0.0, <2.0.0"  # 范围

# 精确版本
serde = "=1.0.193"

# 通配符
serde = "1.*"
serde = "*"

详细配置 #

toml

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", default-features = false, features = ["rt", "net"] }

Git 依赖 #

toml

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

# 指定分支
my_lib = { git = "https://github.com/user/my_lib.git", branch = "main" }

# 指定标签
my_lib = { git = "https://github.com/user/my_lib.git", tag = "v1.0.0" }

# 指定提交
my_lib = { git = "https://github.com/user/my_lib.git", rev = "abc123" }

路径依赖 #

toml

[dependencies]
my_lib = { path = "../my_lib" }
my_lib = { path = "../my_lib", version = "0.1.0" }

可选依赖 #

toml

[dependencies]
serde_json = { version = "1.0", optional = true }

[features]
json = ["serde_json"]

重命名依赖 #

toml

[dependencies]
my_serde = { package = "serde", version = "1.0" }

[dev-dependencies] 部分 #

开发依赖，仅在测试、示例和基准测试中使用。

toml

[dev-dependencies]
tokio = { version = "1.0", features = ["full"] }
tempfile = "3.0"
criterion = "0.5"

[build-dependencies] 部分 #

构建脚本依赖，仅在构建脚本中使用。

toml

[build-dependencies]
cc = "1.0"
bindgen = "0.69"

[target] 部分 #

平台特定的依赖和配置。

目标特定依赖 #

toml

[target.'cfg(windows)'.dependencies]
winapi = "0.3"

[target.'cfg(unix)'.dependencies]
libc = "0.2"

[target.'cfg(target_arch = "x86_64")'.dependencies]
x86 = "0.52"

[target.x86_64-pc-windows-msvc.dependencies]
winapi = "0.3"

[target.'cfg(all(unix, not(target_os = "macos")))'.dependencies]
openssl = "0.10"

目标特定 dev-dependencies #

toml

[target.'cfg(unix)'.dev-dependencies]
nix = "0.27"

目标特定 build-dependencies #

toml

[target.'cfg(windows)'.build-dependencies]
winres = "0.1"

[features] 部分 #

特性标志，用于条件编译。

基本语法 #

toml

[features]
default = ["feature1", "feature2"]
feature1 = []
feature2 = ["dep:some_dep"]
feature3 = ["feature1", "dep:another_dep"]

启用可选依赖 #

toml

[dependencies]
serde = { version = "1.0", optional = true }
serde_json = { version = "1.0", optional = true }

[features]
default = ["serde"]
serde = ["dep:serde"]
json = ["dep:serde_json", "serde"]

特性使用 #

bash

# 启用默认特性
cargo build

# 禁用默认特性
cargo build --no-default-features

# 启用特定特性
cargo build --features "feature1,feature2"

# 启用所有特性
cargo build --all-features

依赖特性 #

toml

[features]
# 启用依赖的特性
full = ["tokio/full", "serde/derive"]

[profile] 部分 #

编译配置文件。

内置配置文件 #

Profile	用途	优化级别	调试信息
dev	开发	0	完整
release	发布	3	无
test	测试	0	完整
bench	性能测试	3	无

自定义配置 #

toml

[profile.dev]
opt-level = 0
debug = true
split-debuginfo = "..."
debug-assertions = true
overflow-checks = true
lto = false
panic = 'unwind'
incremental = true
codegen-units = 256
rpath = false

[profile.release]
opt-level = 3
debug = false
split-debuginfo = "..."
debug-assertions = false
overflow-checks = false
lto = false
panic = 'unwind'
incremental = false
codegen-units = 16
rpath = false
strip = false

配置项详解 #

opt-level #

优化级别。

toml

[profile.release]
opt-level = 0    # 无优化
opt-level = 1    # 基本优化
opt-level = 2    # 一些优化
opt-level = 3    # 全部优化
opt-level = "s"  # 优化大小
opt-level = "z"  # 更小的大小

debug #

调试信息级别。

toml

[profile.dev]
debug = true          # 完整调试信息
debug = false         # 无调试信息
debug = 0             # 无调试信息
debug = 1             # 行信息
debug = 2             # 完整调试信息

lto #

链接时优化。

toml

[profile.release]
lto = false      # 禁用
lto = true       # 完全 LTO
lto = "thin"     # Thin LTO（更快）
lto = "fat"      # 完全 LTO

codegen-units #

代码生成单元数。

toml

[profile.release]
codegen-units = 1    # 最慢，最佳优化
codegen-units = 16   # 较快，较少优化

panic #

panic 策略。

toml

[profile.release]
panic = "unwind"    # 展开栈（默认）
panic = "abort"     # 直接终止

strip #

移除符号信息。

toml

[profile.release]
strip = false       # 保留符号
strip = true        # 移除符号
strip = "symbols"   # 移除符号
strip = "debuginfo" # 移除调试信息
strip = "none"      # 保留所有

继承配置 #

toml

[profile.release-lto]
inherits = "release"
lto = true
codegen-units = 1

包特定配置 #

toml

[profile.release.package.my_package]
opt-level = 3

[profile.release.package."*"]
opt-level = 2

[workspace] 部分 #

工作区配置，用于管理多包项目。

toml

[workspace]
members = ["crates/*", "apps/*"]
exclude = ["crates/experimental"]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2021"
license = "MIT"

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

[lib] 和 [[bin]] 部分 #

定义库和二进制目标。

[lib] 配置 #

toml

[lib]
name = "my_lib"
path = "src/lib.rs"
test = true
doctest = true
bench = true
doc = true
plugin = false
proc-macro = false
harness = true
edition = "2021"
crate-type = ["lib"]
required-features = []

[[bin]] 配置 #

toml

[[bin]]
name = "my_app"
path = "src/main.rs"
test = true
bench = true
doc = true

[[bin]]
name = "cli"
path = "src/bin/cli.rs"

[[example]] 配置 #

toml

[[example]]
name = "basic"
path = "examples/basic.rs"

[[example]]
name = "advanced"
path = "examples/advanced.rs"
required-features = ["feature1"]

[[test]] 配置 #

toml

[[test]]
name = "integration"
path = "tests/integration.rs"

[[test]]
name = "common"
path = "tests/common/mod.rs"
harness = false

[[bench]] 配置 #

toml

[[bench]]
name = "performance"
path = "benches/performance.rs"
harness = false

[patch] 部分 #

覆盖依赖。

toml

[patch.crates-io]
serde = { git = "https://github.com/serde-rs/serde.git" }

[patch."https://github.com/user/my_lib"]
my_lib = { path = "../my_local_lib" }

[replace] 部分 #

替换依赖（已弃用，推荐使用 [patch]）。

toml

[replace]
"serde:1.0.0" = { git = "https://github.com/serde-rs/serde.git" }

完整配置示例 #

toml

[package]
name = "my_awesome_project"
version = "0.1.0"
edition = "2021"
rust-version = "1.70"
description = "A fast and secure web framework"
documentation = "https://docs.rs/my_awesome_project"
readme = "README.md"
homepage = "https://myproject.com"
repository = "https://github.com/user/my_awesome_project"
license = "MIT OR Apache-2.0"
keywords = ["web", "framework", "async"]
categories = ["web-programming", "asynchronous"]
authors = ["John Doe <john@example.com>"]
exclude = ["docs/*", "tests/*"]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = { version = "1.0", optional = true }
tokio = { version = "1.0", default-features = false, features = ["rt", "net"] }

[target.'cfg(windows)'.dependencies]
winapi = "0.3"

[target.'cfg(unix)'.dependencies]
libc = "0.2"

[dev-dependencies]
tokio = { version = "1.0", features = ["full"] }
tempfile = "3.0"

[build-dependencies]
cc = "1.0"

[features]
default = ["serde"]
serde = ["dep:serde"]
json = ["dep:serde_json", "serde"]
full = ["json", "tokio/full"]

[lib]
name = "my_lib"
path = "src/lib.rs"

[[bin]]
name = "my_app"
path = "src/main.rs"

[[example]]
name = "basic"
path = "examples/basic.rs"

[profile.dev]
opt-level = 0
debug = true

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true

[profile.release-lto]
inherits = "release"
lto = "thin"

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

下一步 #

了解了 Cargo.toml 配置后，继续学习依赖管理深入掌握依赖管理技巧！