rust

Rust 工具链精讲：Cargo 高级特性、交叉编译与质量门禁

Rust 工具链深度指南：Cargo 工作区与高级特性、条件编译、cross 交叉编译、cargo-bloat/audit/deny 质量工具、rustup 工具链管理、Crates.io 发布流程与 CI 缓存优化。

Leeting Yan 2026-09-28 4 分钟阅读 1661 字

1. rustup 工具链管理

rustup 管理 Rust 版本、目标平台与组件：

# 安装/更新
rustup update                    # 更新 stable/nightly
rustup install 1.80.0            # 安装指定版本

# 切换版本
rustup default 1.80.0            # 默认版本
rustup override set nightly      # 当前目录用 nightly（rust-toolchain 文件）
rustup show                      # 查看当前工具链

# 组件
rustup component add rustfmt clippy llvm-tools
rustup component remove clippy

# 目标平台
rustup target add x86_64-unknown-linux-musl aarch64-apple-darwin
rustup target list --installed

rust-toolchain.toml 文件固化团队工具链：

[toolchain]
channel = "1.80.0"        # 锁定版本
components = ["clippy", "rustfmt"]
targets = ["x86_64-unknown-linux-musl", "aarch64-apple-darwin"]

2. Cargo 工作区与依赖管理

多 crate 项目用 workspace 统一管理。

# Cargo.toml（根）
[workspace]
members = ["crates/parser", "crates/core", "crates/cli"]
resolver = "2"

[workspace.dependencies]          # 统一版本，避免漂移
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[workspace.package]               # 统一元数据
version = "1.2.0"
license = "MIT"

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

2.1 依赖版本语义

[dependencies]
# 1.0.0        → 恰好 1.0.0
# 1.0          → >=1.0.0, <2.0.0（Caret 默认）
# 1.0.3        → >=1.0.3, <1.1.0
# ~1.0.3       → >=1.0.3, <1.1.0
# ~1.0         → >=1.0.0, <1.1.0
# 0.8.x 用 ~0.8 → 0.8.x 微版本更新
serde = "1.0"

3. Cargo 高级特性

3.1 cargo alias

# ~/.cargo/config.toml
[alias]
b = "build"
r = "run"
t = "test"
c = "check"
br = "build --release"
tc = "test -- --nocapture"

3.2 依赖替换与补丁

# 覆盖特定 crate 版本（git 分支）
[patch.crates-io]
my-crate = { git = "https://github.com/me/my-crate", branch = "fix" }

# 本地路径调试
[dependencies]
my-crate = { path = "../my-crate" }

3.3 配置文件源

# ~/.cargo/config.toml
[build]
jobs = 8                    # 并行编译数
rustflags = ["-C", "target-cpu=native"]

[net]
retry = 5

4. 条件编译与 feature 门控

#[cfg(target_os = "linux")]
fn platform_info() -> &'static str { "Linux" }

#[cfg(target_os = "windows")]
fn platform_info() -> &'static str { "Windows" }

#[cfg(feature = "tls")]
fn secure() {}

#[cfg(not(feature = "tls"))]
fn secure() { /* 明文实现 */ }

feature 定义：

[features]
default = ["std"]
std = []
full = ["tls", "http2"]
tls = ["dep:rustls"]
http2 = ["dep:h2"]

[dependencies]
rustls = { version = "0.23", optional = true }
h2 = { version = "0.4", optional = true }

cargo build --no-default-features   # 去默认
cargo build --features full         # 开全部

feature 最佳实践：默认尽量精简；feature 只用 dep: 前缀避免隐式；语义化版本：加 feature 是 minor，删 feature 是 breaking。

5. 交叉编译 cross

cross 基于 Docker 的交叉编译神器，一条命令编译任意目标。

# 安装
cargo install cross

# 编译 Linux musl 静态二进制（零依赖分发）
cross build --release --target x86_64-unknown-linux-musl

# 编译 Windows
cross build --release --target x86_64-pc-windows-gnu

# 编译 ARM 嵌入式
cross build --release --target aarch64-unknown-linux-gnu

直接 rustup target 交叉编译（本地有工具链时）：

# macOS → Linux
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

# macOS → ARM macOS
rustup target add aarch64-apple-darwin
cargo build --release --target aarch64-apple-darwin

各目标用途：

target	用途
`x86_64-unknown-linux-musl`	静态 Linux 二进制，一键 scp 即用
`aarch64-apple-darwin`	Apple Silicon macOS
`x86_64-pc-windows-msvc`	Windows MSVC
`thumbv7em-none-eabihf`	嵌入式无操作系统

6. 质量门禁 cargo audit / deny

6.1 cargo-audit（漏洞扫描）

cargo install cargo-audit
cargo audit                 # 扫描依赖已知漏洞
cargo audit --json          # 机器可读输出

6.2 cargo-deny（许可/来源/重复依赖）

# deny.toml
[licenses]
allow = ["MIT", "Apache-2.0", "BSD-3-Clause"]

[bans]
multiple-versions = "warn"

[sources]
allow-git = ["https://github.com/"]
allow-registry = ["https://github.com/rust-lang/crates.io-index"]

cargo deny check licenses    # 许可合规
cargo deny check bans        # 版本冲突
cargo deny check sources     # 依赖来源审计

6.3 CI 门禁组合

# .github/workflows/quality.yml
jobs:
  quality:
    steps:
      - run: cargo fmt --check
      - run: cargo clippy -- -D warnings
      - run: cargo audit
      - run: cargo deny check
      - run: cargo test

7. 体积优化 cargo bloat

cargo install cargo-bloat

# 各依赖体积排名
cargo bloat --release --top 20

# 定位大函数
cargo bloat --release -n hello

# 各目标文件大小
cargo bloat --release --split-std

减体积三板斧：

手段	效果
`strip = true`	去符号表，可减 30-50%
`lto = "thin"`	跨 crate 内联，减 10-30%
`opt-level = "z"`	体积优先优化
`codegen-units = 1`	全局优化（编译变慢）

[profile.release]
strip = true
lto = "thin"
opt-level = "z"
codegen-units = 1
panic = "abort"   # 不用 unwinding，进一步减体积

8. 构建缓存与 CI 优化

8.1 本地缓存

# ~/.cargo/config.toml
[build]
# sccache：分布式缓存，多机器共享

cargo install sccache
export RUSTC_WRAPPER=sccache

8.2 CI 缓存策略

# GitHub Actions 缓存 ~/.cargo 与 target
- uses: actions/cache@v3
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}

8.3 加速技巧

cargo check          # 只做类型检查，快得多
cargo build -Z timings   # nightly：构建耗时火焰图
CARGO_INCREMENTAL=1 cargo build   # 增量编译

9. Crates.io 发布流程

# 1. 检查
cargo fmt --check && cargo clippy && cargo test
cargo publish --dry-run        # 预演

# 2. 版本号
cargo release patch            # 或手动改 Cargo.toml version

# 3. 生成 changelog
cargo install git-cliff
git cliff -o CHANGELOG.md

# 4. 发布
cargo publish

# 5. 打 tag
git tag v1.2.0
git push origin --tags

发布前 checklist：

项	检查
README	有徽章、示例、说明
文档	`cargo doc` 无断链，`#![warn(missing_docs)]`
license	有 LICENSE 文件
版本约束	无 `*` 依赖
二进制	含 `[[bin]]` 或作为 lib 无 bin
分类/关键词	`cargo publish` 校验通过

发布后撤回（只有 24h 内无依赖时）：

cargo yank v1.2.0 --undo

10. 速查表与常用命令

命令	作用
`cargo new <name> --vcs git`	新项目
`cargo add serde --features derive`	加依赖
`cargo tree -i tokio`	谁依赖了 tokio
`cargo update -p tokio`	升级指定 crate
`cargo expand`（nightly）	宏展开
`cargo llvm-cov`	覆盖率
`cargo nextest`	更快的测试运行器
`cargo machete`	找未使用依赖

一句话记忆：工具链 = rustup 管版本 + Cargo 管依赖 + cross 管交叉编译 + audit/deny/bloat 管质量 + cargo-dist/cargo-release 管发布，CI 里串成一条流水线即可。

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页