rustfmt 代码格式化
什么是 rustfmt
rustfmt 是 Rust 官方的代码格式化工具,它按照统一的风格规范自动调整代码的缩进、空格、换行、对齐等排版细节。运行一条 cargo fmt 命令,整个项目的代码风格就能统一。
和手动调格式相比,用 rustfmt 的好处是团队不需要在"花括号放哪一行"、"缩进用几个空格"这类问题上反复讨论。所有人用同一份格式化规则,代码看起来就像一个人写的。在代码审查时也不会出现"纯格式修改"的 commit 干扰真正的逻辑变更。
安装
rustfmt 是 Rustup 的官方组件,通常默认已安装。如果没有:
# 安装 rustfmt 组件
rustup component add rustfmt
# 验证安装
rustfmt --version
# 输出类似:rustfmt 1.8.0-stable (e2014e876 2026-03-17)基本用法
# 格式化当前项目的所有 Rust 源文件
# 会直接修改文件内容
cargo fmt
# 只检查格式是否正确,不修改文件
# 如果有格式问题会返回非零退出码并显示 diff
# CI 中常用这个命令
cargo fmt -- --check
# 格式化单个文件
rustfmt src/main.rs
# 格式化时显示修改了哪些内容
cargo fmt -- --verbose格式化前后对比
格式化前(风格混乱的代码):
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 后:
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 配置文件。
# 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_width | 100 | 单行最大字符数 |
hard_tabs | false | 是否使用 Tab 缩进 |
tab_spaces | 4 | 每级缩进空格数 |
edition | "2015" | 使用的 Rust edition(建议设为项目实际 edition) |
use_small_heuristics | "Default" | 启发式规则(控制多种换行行为) |
如果你想用 nightly 才有的配置项,可以在文件开头加一行:
# 声明使用不稳定特性(需要 nightly rustfmt)
unstable_features = true然后用 nightly 版本运行:cargo +nightly fmt。
跳过格式化
有些代码片段你不希望 rustfmt 去碰(比如手动对齐的表格状数据),可以用属性标记跳过:
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),
]
}也可以用特殊注释跳过一段代码:
fn main() {
// 正常格式化的代码
let a = 1;
// @formatter:off 或 rustfmt 的 skip 属性
#[rustfmt::skip]
{
let b = 2 ; // 这里的多余空格不会被移除
let c=3; // 这里缺少的空格不会被添加
}
// 继续正常格式化
let d = 4;
}基本示例
在一个实际项目中集成 rustfmt 的完整流程:
# 创建项目
cargo new fmt-demo
cd fmt-demo创建 rustfmt.toml 配置文件:
# rustfmt.toml
max_width = 100
tab_spaces = 4
edition = "2021"编辑 src/main.rs:
// 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();
}
}# 格式化代码
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 检查),就能彻底告别代码风格不一致的烦恼。