Cargo 進階功能：Features 與 Profiles

簡介

在 Rust 生態系統中，Cargo 不只是編譯、測試與發佈的工具，它同時提供了許多讓專案更具彈性與可維護性的功能。當專案規模變大、需求多樣化時，Features 與 Profiles 就成為必備的利器。

• Features 讓你可以在同一個 crate 中條件式地啟用或關閉功能，減少不必要的依賴與編譯時間。
• Profiles 則提供了多種建置設定（如 debug、release、custom），讓你在開發、測試、部署時能取得最佳的效能或除錯資訊。

掌握這兩個概念，能讓你的 Rust 專案在 可組合性、編譯速度 以及 執行效能 上都得到顯著提升。下面我們將一步步說明如何在 Cargo.toml 中配置與使用這些進階功能，並提供實作範例與最佳實踐。

---

核心概念

1. Features：條件式依賴與功能切換

1.1 為什麼需要 Features

在大型程式庫（library）中，往往會提供多種可選功能（例如：支援不同的資料庫、加密演算法、或是額外的 CLI 工具）。如果把所有功能全部編譯進去，會產生以下問題：

1. 編譯時間變長
2. 二進位檔案尺寸膨脹
3. 不必要的依賴可能帶來安全風險

使用 Features，使用者可以自行決定要啟用哪些功能，Cargo 會自動處理相依性與編譯選項。

1.2 基本語法

在 Cargo.toml 中的 [features] 區段定義：

[features]
default = ["json"]          # 預設啟用的 feature
json    = ["serde_json"]    # 啟用 json 時會自動帶入 serde_json
yaml    = ["serde_yaml"]    # 啟用 yaml 時會自動帶入 serde_yaml
tls     = ["native-tls"]    # TLS 支援

• default 為 預設啟用 的 feature 集合。
• 每個 feature 可以是 其他 feature（依賴）或 外部 crate（依賴的套件）。

1.3 在程式碼中使用

Cargo 會在編譯時為每個 feature 產生 cfg 標記，我們可以透過 #[cfg(feature = "...")] 來條件編譯程式碼：

// src/lib.rs
#[cfg(feature = "json")]
pub fn parse_json(input: &str) -> Result<serde_json::Value, serde_json::Error> {
    serde_json::from_str(input)
}

#[cfg(feature = "yaml")]
pub fn parse_yaml(input: &str) -> Result<serde_yaml::Value, serde_yaml::Error> {
    serde_yaml::from_str(input)
}

使用者只要在 Cargo.toml 中加入所需的 feature，對應的函式就會被編譯進去。

1.4 啟用 / 禁用 Feature

# 啟用 json 與 tls
cargo build --features "json tls"

# 禁用預設的 feature，只保留 yaml
cargo build --no-default-features --features "yaml"

1.5 範例：可選的日誌功能

# Cargo.toml
[dependencies]
log = "0.4"

[features]
default = []                     # 預設不啟用任何日誌
env_logger = ["log", "env_logger"]   # 啟用 env_logger 時自動加入依賴

// src/lib.rs
#[cfg(feature = "env_logger")]
pub fn init_logging() {
    env_logger::init();
}

#[cfg(not(feature = "env_logger"))]
pub fn init_logging() {
    // No‑op：當未啟用日誌時保持靜默
}

---

2. Profiles：自訂建置設定

2.1 內建的三個基本 Profile

Profile	典型用途	主要設定
dev	開發階段、頻繁編譯	debug = true、opt-level = 0
release	發佈、正式部署	debug = false、opt-level = 3
test	單元測試、整合測試	與 dev 類似，但允許測試專用設定

Cargo 會根據 cargo build（預設使用 dev）或 cargo build --release（使用 release）自動選擇對應的 profile。

2.2 自訂 Profile

從 Cargo 1.56 起，我們可以在 Cargo.toml 中自行新增 profile，並在指令列使用 --profile <name>：

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

[profile.release]
opt-level = 3
debug = false
lto = true               # Link Time Optimization
codegen-units = 1        # 單一 codegen 單元，提升最佳化

[profile.bench]
inherits = "release"
debug = true             # 保留除錯資訊，方便分析效能

使用方式：

cargo build --profile bench   # 以 bench 設定編譯

2.3 常見的 Profile 調校項目

設定項目	說明	常見值
opt-level	編譯最佳化等級，0~3 或 s（size）/z（更小）	0（無最佳化）~`3`（最高）
debug	是否保留除錯資訊（true 產生較大二進位）	true / false
lto	Link Time Optimization，減少二進位大小與提升效能	false / true / "thin"
codegen-units	編譯單元數，越少越有機會取得更好最佳化	1（單元）~`N`（預設）
panic	Panic 行為：unwind（可恢復）或 abort（直接退出）	"unwind" / "abort"
incremental	增量編譯，提升開發階段編譯速度	true / false

---

3. 程式碼範例：結合 Features 與 Profiles

以下示範一個簡易的 CLI 程式，支援 JSON 與 YAML 兩種輸入格式，並提供 debug 與 release 兩種建置設定。

# Cargo.toml
[package]
name = "config-cli"
version = "0.1.0"
edition = "2021"

[dependencies]
clap = { version = "4", features = ["derive"] }

# 可選的序列化格式
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", optional = true }
serde_yaml = { version = "0.9", optional = true }

[features]
default = ["json"]          # 預設只支援 JSON
json = ["serde_json"]
yaml = ["serde_yaml"]

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = "abort"

// src/main.rs
use clap::Parser;
use serde::Deserialize;

#[derive(Parser)]
struct Args {
    /// 輸入檔案路徑
    #[arg(short, long)]
    input: String,

    /// 輸入格式：json 或 yaml
    #[arg(short, long, default_value = "json")]
    format: String,
}

#[derive(Debug, Deserialize)]
struct Config {
    name: String,
    version: u32,
}

#[cfg(feature = "json")]
fn parse(input: &str) -> Result<Config, serde_json::Error> {
    serde_json::from_str(input)
}

#[cfg(feature = "yaml")]
fn parse(input: &str) -> Result<Config, serde_yaml::Error> {
    serde_yaml::from_str(input)
}

fn main() {
    let args = Args::parse();

    let content = std::fs::read_to_string(&args.input)
        .expect("無法讀取檔案");

    // 依據 feature 與 format 呼叫對應的 parser
    let cfg = match args.format.as_str() {
        "json" => parse(&content).expect("JSON 解析失敗"),
        "yaml" => parse(&content).expect("YAML 解析失敗"),
        _ => panic!("不支援的格式"),
    };

    // 在 debug profile 中印出詳細資訊
    #[cfg(debug_assertions)]
    println!("Parsed config (debug): {:#?}", cfg);

    // 在 release profile 中只印出簡潔資訊
    #[cfg(not(debug_assertions))]
    println!("Config: {} v{}", cfg.name, cfg.version);
}

說明

• 透過 #[cfg(feature = "...")] 為不同的序列化格式提供獨立的 parse 函式。
• debug_assertions 會在 dev（debug）profile 中自動啟用，讓我們在開發時看到更詳細的除錯資訊。
• 若要編譯支援 YAML，只需：

cargo build --release --features "yaml"

---

常見陷阱與最佳實踐

陷阱	說明	解決方案 / 最佳實踐
Feature 依賴循環	兩個 crate 互相依賴對方的 feature，會導致 Cargo 無法解析。	使用 optional dependencies + feature aggregation，避免直接相互依賴。
預設 feature 過多	把太多功能放入 default，使用者無法自行裁剪。	僅把 最常用且不增加額外依賴 的功能列入 default，其他保持 optional。
Profile 設定遺忘	在 release 中忘記關閉 debug，導致二進位過大。	在 CI/CD pipeline 中明確指定 --release，或在 Cargo.toml 中把 debug = false 設為預設。
LTO 與增量編譯衝突	開啟 lto = true 後，增量編譯 (incremental = true) 會失效，編譯速度變慢。	在開發階段保留 incremental = true，在正式發佈時改為 lto = true。
panic = "abort" 與測試衝突	abort 會導致測試框架無法捕捉 panic，測試失敗。	只在 release profile 設定 panic = "abort"，測試仍使用 unwind。

最佳實踐

1. 最小化 default feature：只保留「幾乎所有使用者都需要」的功能。
2. 使用 feature gating：在程式碼中加入 #[cfg(feature = "...")]，確保未啟用的程式碼不會被編譯。
3. 為每個 profile 撰寫說明文件：讓團隊成員清楚何時使用 dev、release、或自訂 profile。
4. 在 CI 中測試所有 feature 組合：利用 cargo test --all-features 確保每個組合都能順利編譯與通過測試。
5. 利用 cargo bench 與自訂 profile：針對效能基準測試使用 bench profile，保留除錯資訊同時啟用最佳化。

---

實際應用場景

場景	為何需要 Features	為何需要 Profiles
跨平台 GUI 庫（例如 egui）	不同平台可能需要不同的渲染後端（OpenGL、Vulkan、WebGPU），透過 feature 選擇性編譯。	開發時使用 dev（快速編譯），發佈時使用 release（最高效能）或自訂 size-opt（縮小二進位）。
CLI 工具（如 ripgrep）	可選的正則表達式引擎、彩色輸出、壓縮支援等，讓使用者自行決定。	在 CI 中使用 --profile bench 產生含除錯資訊的效能測試二進位，正式發佈則使用 release。
嵌入式韌體	嵌入式環境常常只能保留核心功能，其他功能如 std、alloc 必須關閉。	使用 panic = "abort"、opt-level = "z"（最小化尺寸）以及 codegen-units = 1 取得最小且快速的韌體。
WebAssembly（wasm）套件	需要分離 std 與 no_std 的實作，透過 feature 切換。	wasm 目標的 release profile 常會開啟 lto = "thin" 以減少 bundle 大小。

---

總結

Features 與 Profiles 是 Cargo 提供的兩大進階機制，分別解決 功能可組合性 與 建置效能 的需求。透過 條件式依賴（feature gating）與 自訂建置設定（profile），我們可以：

• 減少編譯時間：只編譯實際需要的程式碼與相依套件。
• 縮小二進位尺寸：在 release 或嵌入式環境中關閉不必要的功能與除錯資訊。
• 提升執行效能：使用 LTO、最佳化等 profile 設定，讓程式在正式環境中跑得更快。
• 提升維護性：每個 feature 都有明確的依賴與說明，讓新加入的開發者能快速了解專案的組件結構。

在日常開發中，建議先 規劃好 feature 的粒度，再根據不同的部署需求設計 相應的 profile。最後，別忘了在 CI 中跑 cargo test --all-features 與 cargo build --profile <custom>，確保所有組合都能正確編譯與運作。掌握了這些技巧，你的 Rust 專案將會變得更靈活、更高效，也更容易在團隊與社群中維護與擴充。祝開發順利！