rustfmt 代码格式化 ​

什么是 rustfmt ​

rustfmt 是 Rust 官方的代码格式化工具,它按照统一的风格规范自动调整代码的缩进、空格、换行、对齐等排版细节。运行一条 cargo fmt 命令,整个项目的代码风格就能统一。

和手动调格式相比,用 rustfmt 的好处是团队不需要在"花括号放哪一行"、"缩进用几个空格"这类问题上反复讨论。所有人用同一份格式化规则,代码看起来就像一个人写的。在代码审查时也不会出现"纯格式修改"的 commit 干扰真正的逻辑变更。

安装 ​

rustfmt 是 Rustup 的官方组件,通常默认已安装。如果没有:

powershell
# 安装 rustfmt 组件
rustup component add rustfmt

# 验证安装
rustfmt --version
# 输出类似:rustfmt 1.8.0-stable (e2014e876 2026-03-17)

基本用法 ​

powershell
# 格式化当前项目的所有 Rust 源文件
# 会直接修改文件内容
cargo fmt

# 只检查格式是否正确,不修改文件
# 如果有格式问题会返回非零退出码并显示 diff
# CI 中常用这个命令
cargo fmt -- --check

# 格式化单个文件
rustfmt src/main.rs

# 格式化时显示修改了哪些内容
cargo fmt -- --verbose

格式化前后对比 ​

格式化前(风格混乱的代码):

rust
fn main(){
let     x=5;
    let y = 10;
  if x>0{
println!("x is positive: {}",x);
    }
    let result = if y>5 {
"big"
}else{
"small"
    };
let numbers=vec![1,2,3,4,5];
for n in numbers.iter()
{
println!("{}",n);
}
}

运行 cargo fmt 后:

rust
fn main() {
    // 缩进统一为 4 个空格
    let x = 5;
    let y = 10;

    // 运算符两边加空格,花括号位置规范
    if x > 0 {
        println!("x is positive: {}", x);
    }

    // if/else 表达式格式统一
    let result = if y > 5 { "big" } else { "small" };

    // 集合字面量中逗号后加空格
    let numbers = vec![1, 2, 3, 4, 5];

    // for 循环的花括号跟在同一行
    for n in numbers.iter() {
        println!("{}", n);
    }
}

自定义格式化规则 ​

如果你想调整 rustfmt 的默认行为,可以在项目根目录创建 rustfmt.toml 或 .rustfmt.toml 配置文件。

toml
# rustfmt.toml
# 放在项目根目录(和 Cargo.toml 同级)

# 单行最大宽度,超过会自动换行(默认 100)
max_width = 100

# 缩进使用空格(默认)还是 Tab
hard_tabs = false

# 每级缩进的空格数(默认 4)
tab_spaces = 4

# 函数参数换行策略
# "Tall":每个参数一行
# "Compressed":尽量压缩到一行
# "Visual":和第一个参数对齐
fn_params_layout = "Tall"

# use 语句分组策略
# "StdExternalCrate":标准库、外部 crate、本地 crate 分组
imports_granularity = "Crate"

# 是否在每个 use 分组之间加空行
group_imports = "StdExternalCrate"

# 单行 if/else 表达式的最大宽度
single_line_if_else_max_width = 50

# 是否在结构体字段末尾加逗号
trailing_comma = "Vertical"

# 注释最大宽度
comment_width = 80

# 是否格式化文档注释中的代码块
format_code_in_doc_comments = true

需要注意的是,很多配置项属于"不稳定"(unstable)选项,只在 nightly 版本的 rustfmt 中可用。在 stable 版本中能用的配置项比较有限。

稳定版可用的常用配置 ​

配置项默认值说明
max_width100单行最大字符数
hard_tabsfalse是否使用 Tab 缩进
tab_spaces4每级缩进空格数
edition"2015"使用的 Rust edition(建议设为项目实际 edition)
use_small_heuristics"Default"启发式规则(控制多种换行行为)

如果你想用 nightly 才有的配置项,可以在文件开头加一行:

toml
# 声明使用不稳定特性(需要 nightly rustfmt)
unstable_features = true

然后用 nightly 版本运行:cargo +nightly fmt。

跳过格式化 ​

有些代码片段你不希望 rustfmt 去碰(比如手动对齐的表格状数据),可以用属性标记跳过:

rust
fn main() {
    // 正常的代码会被格式化
    let x = 5;
    let y = 10;

    // 用 #[rustfmt::skip] 标记的代码不会被格式化
    #[rustfmt::skip]
    let matrix = [
        [1,  0,  0,  0],
        [0,  1,  0,  0],
        [0,  0,  1,  0],
        [0,  0,  0,  1],
    ];

    println!("{:?}", matrix);
}

// 整个函数跳过格式化
#[rustfmt::skip]
fn hand_formatted_table() -> Vec<(&'static str, i32)> {
    vec![
        ("Alice",   90),
        ("Bob",     85),
        ("Charlie", 92),
    ]
}

也可以用特殊注释跳过一段代码:

rust
fn main() {
    // 正常格式化的代码
    let a = 1;

    // @formatter:off 或 rustfmt 的 skip 属性
    #[rustfmt::skip]
    {
        let b = 2 ;  // 这里的多余空格不会被移除
        let c=3;     // 这里缺少的空格不会被添加
    }

    // 继续正常格式化
    let d = 4;
}

基本示例 ​

在一个实际项目中集成 rustfmt 的完整流程:

powershell
# 创建项目
cargo new fmt-demo
cd fmt-demo

创建 rustfmt.toml 配置文件:

toml
# rustfmt.toml
max_width = 100
tab_spaces = 4
edition = "2021"

编辑 src/main.rs:

rust
// src/main.rs

// 定义一个结构体
struct User {
    name: String,
    age: u32,
    email: String,
}

impl User {
    // 创建新用户的关联函数
    fn new(name: &str, age: u32, email: &str) -> Self {
        User {
            name: name.to_string(),
            age,
            email: email.to_string(),
        }
    }

    // 格式化显示用户信息
    fn display(&self) {
        println!("姓名:{},年龄:{},邮箱:{}", self.name, self.age, self.email);
    }
}

fn main() {
    // 创建用户列表
    let users = vec![
        User::new("张三", 28, "zhangsan@example.com"),
        User::new("李四", 32, "lisi@example.com"),
        User::new("王五", 25, "wangwu@example.com"),
    ];

    // 遍历并显示所有用户
    for user in &users {
        user.display();
    }
}
powershell
# 格式化代码
cargo fmt

# 检查格式是否正确(CI 中使用)
cargo fmt -- --check

常见问题 ​

问题一:cargo fmt 和 rustfmt 有什么区别?

cargo fmt 会格式化整个 Cargo 项目中所有的 Rust 源文件,包括 src/、tests/、examples/ 等目录。rustfmt 直接接收文件路径参数,格式化指定的文件。日常开发用 cargo fmt 更方便。

问题二:rustfmt 会改变代码的逻辑吗?

不会。rustfmt 只改变代码的排版格式(空格、换行、缩进等),不会修改任何语义。格式化前后编译出来的二进制文件是完全一样的。

问题三:团队成员的 rustfmt 版本不一致怎么办?

不同版本的 rustfmt 可能对同一段代码产生不同的格式化结果。建议通过 rust-toolchain.toml 锁定 Rust 版本,因为 rustfmt 版本是跟随 Rust 版本的。这样团队所有人的 rustfmt 版本也会一致。

问题四:格式化后 Git 显示大量修改怎么办?

如果是第一次给项目引入 rustfmt,建议单独做一个 "format all code" 的 commit,和其他逻辑修改分开。之后每次提交前都运行 cargo fmt,就不会出现大量格式化修改了。可以用 Git hooks 在提交前自动运行 cargo fmt。

适用场景 ​

  • 团队开发:统一代码风格,消除格式相关的代码审查评论
  • CI/CD 流水线:cargo fmt -- --check 确保所有提交的代码都经过格式化
  • 提交前自动格式化:配合 Git pre-commit hook 在每次提交时自动运行 cargo fmt
  • 编辑器保存时自动格式化:在 VS Code 中设置 "editor.formatOnSave": true,保存文件时自动调用 rustfmt
  • 开源项目:在贡献指南中要求贡献者运行 cargo fmt,减少维护者的格式化工作

注意事项 ​

  • cargo fmt 会直接修改源文件,运行前确保代码已经提交到 Git(或至少 stage 了),方便回退
  • rustfmt.toml 中很多有趣的配置项需要 nightly 版本才能用,stable 版本的可配置项比较少
  • 不要把 rustfmt.toml 加入 .gitignore,它应该和代码一起版本控制
  • 如果项目中有自动生成的代码文件,可以在 rustfmt.toml 中用 ignore 选项跳过这些文件(nightly 特性)
  • 在 VS Code 中设置 "[rust]": { "editor.defaultFormatter": "rust-lang.rust-analyzer" } 可以让保存时自动格式化使用 rustfmt
  • 宏生成的代码 rustfmt 通常无法格式化,这是正常的

总结 ​

rustfmt 是 Rust 项目中保持代码风格一致的标准工具。通过 cargo fmt 一键格式化整个项目,通过 cargo fmt -- --check 在 CI 中检查格式。默认的格式化规则对大多数项目来说足够用,如果有特殊需求可以通过 rustfmt.toml 文件自定义。不想被格式化的代码段用 #[rustfmt::skip] 标记跳过。把 rustfmt 集成到开发流程中(保存时自动格式化 + CI 检查),就能彻底告别代码风格不一致的烦恼。