自定义 profile ​

核心概念 ​

Profile 是 Cargo 中控制编译器行为的配置集合,包括优化级别、调试信息、溢出检查等。Cargo 内置了四个 profile:dev(开发,cargo build 默认)、release(发布,cargo build --release)、test(测试)和 bench(基准测试)。开发者可以在 Cargo.toml 中通过 [profile.*] 段修改这些 profile 的参数,也可以创建完全自定义的 profile。

toml
# 内置 profile 的默认配置

[profile.dev]
opt-level = 0          # 无优化(编译快)
debug = true           # 包含调试信息
debug-assertions = true # 启用调试断言
overflow-checks = true  # 整数溢出检查
lto = false            # 无链接时优化
panic = "unwind"       # panic 时展开栈
incremental = true     # 增量编译
codegen-units = 256    # 多代码生成单元(编译快)

[profile.release]
opt-level = 3          # 最高优化
debug = false          # 无调试信息
debug-assertions = false
overflow-checks = false
lto = false            # 默认无 LTO
panic = "unwind"
incremental = false
codegen-units = 16

profile 参数 ​

参数可选值说明
opt-level0, 1, 2, 3, "s", "z"优化级别
debugtrue, false, 0, 1, 2调试信息级别
debug-assertionstrue, false调试断言
overflow-checkstrue, false整数溢出检查
ltofalse, true, "thin", "fat"链接时优化
panic"unwind", "abort"panic 策略
incrementaltrue, false增量编译
codegen-units数字代码生成单元数
strip"none", "debuginfo", "symbols"符号剥离
split-debuginfo平台相关调试信息分离

自定义 profile ​

toml
# Rust 1.57+ 支持自定义 profile
# 自定义 profile 必须基于 dev 或 release 继承

# 基于 release 的性能分析 profile
[profile.profiling]
inherits = "release"    # 继承 release 配置
debug = true            # 但保留调试信息(用于 perf/flamegraph)
strip = "none"          # 不剥离符号

# 基于 release 的最小体积 profile
[profile.min-size]
inherits = "release"
opt-level = "z"         # 优化体积
lto = true              # 链接时优化
strip = "symbols"       # 剥离符号
panic = "abort"         # abort 减小体积
codegen-units = 1       # 更好的优化

# 基于 dev 的快速测试 profile
[profile.quick-test]
inherits = "dev"
opt-level = 1           # 轻度优化(测试更快运行)
bash
# 使用自定义 profile
# cargo build --profile profiling
# cargo build --profile min-size
# cargo build --profile quick-test

# 输出目录在 target/<profile-name>/
# cargo build --profile profiling → target/profiling/

覆盖特定依赖的 profile ​

toml
# 为所有依赖使用不同的优化级别
[profile.dev.package."*"]
opt-level = 2           # 依赖库用 opt-level 2(运行更快)
                        # 项目自己的代码仍用 opt-level 0(编译快)

# 为特定依赖配置
[profile.dev.package.serde]
opt-level = 3           # serde 用最高优化

[profile.dev.package.image]
opt-level = 2           # image 库用中等优化

# release 模式下为特定 crate 保留调试信息
[profile.release.package.my-core]
debug = true

基本示例 ​

toml
# 一个实际项目的 profile 配置

[package]
name = "my-server"
version = "0.1.0"
edition = "2024"

# 开发配置:依赖库优化,自己的代码快速编译
[profile.dev]
opt-level = 0

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

# 发布配置:全面优化
[profile.release]
opt-level = 3
lto = "thin"
strip = "symbols"
codegen-units = 1

# 性能分析
[profile.profiling]
inherits = "release"
debug = 2
strip = "none"

# Docker 部署:最小体积
[profile.docker]
inherits = "release"
opt-level = "s"
lto = true
strip = "symbols"
panic = "abort"
codegen-units = 1
rust
fn main() {
    // 检测当前构建配置
    if cfg!(debug_assertions) {
        println!("调试构建 - 包含断言和溢出检查");
    } else {
        println!("发布构建 - 已优化");
    }

    // opt-level 影响运行速度
    let sum: u64 = (0..1_000_000).sum();
    println!("sum = {}", sum);
}

常见问题 ​

问题一:自定义 profile 的输出在哪里?

在 target/<profile-name>/ 目录下。例如 --profile profiling 输出到 target/profiling/。

问题二:inherits 只能继承 dev 或 release 吗?

可以继承任何已定义的 profile(包括其他自定义 profile),但最终根源必须是 dev 或 release。

问题三:[profile.dev.package."*"] 有什么用?

在开发模式下对所有依赖库使用更高的优化级别,而自己的代码保持 opt-level = 0。这让依赖库运行更快(如图像处理、加密),同时保持自己代码的编译速度。

问题四:codegen-units 设为 1 有什么影响?

编译器用单个代码生成单元,可以做更多跨函数优化,生成更快更小的代码,但编译速度变慢。release 构建中推荐设为 1。

适用场景 ​

  • 性能分析:release 优化 + 调试信息
  • 最小体积:LTO + strip + abort + opt-level z
  • 开发体验:依赖优化 + 自身快速编译
  • CI 构建:平衡编译速度和代码质量

注意事项 ​

  • 自定义 profile 必须用 inherits 继承
  • [profile.dev.package."*"] 覆盖所有依赖的配置
  • 自定义 profile 用 --profile name 指定
  • codegen-units = 1 编译慢但优化好
  • opt-level = "s" 和 "z" 优化二进制体积
  • profile 配置影响编译时间和运行性能

总结 ​

Profile 控制编译器的优化级别、调试信息、LTO 等参数。Cargo 内置 dev、release、test、bench 四个 profile。通过 [profile.name] 修改内置配置,通过 inherits 创建自定义 profile。[profile.dev.package."*"] 可以为依赖库单独设置优化级别。常见的自定义 profile 包括性能分析(release + debug info)、最小体积(LTO + strip + abort)等。codegen-units = 1 生成更优代码但编译更慢。