Rust 2026 经验谈 - Rust 2024 Edition 变更全景

edition 迁移的真实流程#

1
1. 修改 Cargo.toml: edition = "2021" → edition = "2024"
2
2. 运行 cargo fix --edition
3
3. 修复 cargo fix 无法自动处理的报告
4
4. 运行 cargo test / cargo clippy 确认

经验谈：不要跳过第 2 步直接手动改。cargo fix --edition 能处理约 80% 的机械变更（如插入 unsafe、调整 lifetime 标注），手动改既容易遗漏又容易改错。我在一个 3 万行的项目迁移中，cargo fix 自动处理了 147 处变更，仅剩 11 处需要手动介入。

1. gen 关键字预留#

RFC 3513 引入了 generator 语法（gen {} 块），为此 gen 被升级为严格保留关键字（strict keyword）。这意味着你不能再将其用作变量名、函数名或模块名。

1
// Edition 2021: 合法
2
fn gen() -> i32 { 42 }
3
let gen = 1;
4

5
// Edition 2024: 编译错误
6
// error: `gen` is a keyword in edition 2024
7
// fn gen() -> i32 { 42 }  // ❌
8
// let gen = 1;              // ❌
9

10
// 修复：重命名
11
fn generate() -> i32 { 42 }
12
let gen_value = 1;

踩坑经验：如果你的项目中有一个叫 gen 的字段（比如 serde 反序列化的 JSON 字段名为 gen），你需要用 #[serde(rename = "gen")] 来桥接：

1
#[derive(serde::Deserialize)]
2
struct Data {
3
    #[serde(rename = "gen")]
4
    gen_value: i32,
5
}

cargo fix --edition 会自动将 gen 标识符重命名为 r#gen（原始标识符语法），但建议手动改为语义更清晰的名字，而不是保留 r#gen 这种生硬的写法。

1b. 预留语法：守护字符串与 ###

RFC 3593 在 2024 Edition 中预留了无前缀守护字符串（#"foo"#）和连续两个及以上 #（##）的语法，为未来的 guarded string literal 做准备。此前 2021 Edition 仅预留了有前缀形式（如 ident##"foo"##）。

1
// Edition 2021: #"foo"# 和 ## 是合法的 token 序列（宏可匹配）
2
// Edition 2024: 编译错误——这些语法已被预留
3

4
// 宏中涉及这些 token 的代码需要调整
5
macro_rules! old_macro {
6
    (# $rest:tt) => { ... };  // ❌ 2024 Edition 中 # 后跟特定 token 可能冲突
7
}

迁移 lint：rust_2024_guarded_string_incompatible_syntax。如果你的宏涉及 #"foo"# 或 ### 等 token 序列，需要重构。

2. RPIT 生命周期捕获规则变更#

这是 2024 Edition 中影响最广泛、也最容易被忽视的变更。RFC 2678 调整了返回位置 impl Trait（RPIT）的 lifetime 捕获规则。

核心变更：在 2021 edition 中，返回 impl Trait 的函数，返回类型默认不捕获任何输入 lifetime（视为 'static），需要手动添加 + '_ 或 + 'a 来标注。2024 edition 中，impl Trait 默认捕获所有在作用域内的输入 lifetime，大幅减少了需要手动标注的场景。

1
use std::fmt::Display;
2

3
// Edition 2021: 多 lifetime 时 impl Trait 视为 'static，编译失败
4
// fn show<'a, 'b>(x: &'a i32, y: &'b i32) -> impl Display {
5
//     if *x > *y { x } else { y }  // ❌ 返回值可能不满足 'static
6
// }
7

8
// Edition 2021 修复：显式标注 outlive 关系
9
fn show_2021<'a, 'b>(x: &'a i32, y: &'b i32) -> impl Display + 'a + 'b {
10
    if *x > *y { x } else { y }
11
}
12

13
// Edition 2024: 默认捕获所有输入 lifetime，编译通过
14
fn show_2024<'a, 'b>(x: &'a i32, y: &'b i32) -> impl Display {
15
    if *x > *y { x } else { y }  // ✅
16
}
17

18
// Edition 2024: 如需不捕获某些 lifetime，用 + use<> 排除
19
fn show_partial<'a, 'b>(x: &'a i32, _y: &'b i32) -> impl Display + use<'a> {
20
    x  // 只捕获 'a，不捕获 'b
21
}

为什么这样改？旧规则在多 lifetime 场景下默认视为 'static，导致开发者必须反复手动标注 + 'a，且容易遗漏。新规则让最常见的”捕获所有 lifetime”成为默认行为，仅在需要排除时才用 + use<> 显式表达。

实际影响：如果你库中的 impl Trait 返回类型之前已经手动标注了 + 'a 等约束，迁移后这些标注仍然有效但可能冗余。cargo fix 会提示可移除的冗余标注。对于之前因缺少标注而用 + '_ 的地方，现在可以去掉。

3. unsafe extern 与外部函数要求#

RFC 3484 规定：在 2024 Edition 中，extern block 本身必须写成 unsafe extern，外部项再按真实契约标记为 safe 或默认 unsafe。调用 unsafe 外部函数仍必须放在 unsafe 块内。

1
unsafe extern "C" {
2
    pub safe fn abs(input: i32) -> i32;
3
    pub fn getenv(name: *const std::ffi::c_char) -> *mut std::ffi::c_char;
4
}
5

6
// safe 外部项可以直接调用
7
fn call_abs(x: i32) -> i32 {
8
    abs(x)
9
}
10

11
// unsafe 外部项仍必须加 unsafe
12
fn read_env(name: *const std::ffi::c_char) -> *mut std::ffi::c_char {
13
    // SAFETY: 调用者保证 name 是以 NUL 结尾的有效 C 字符串
14
    unsafe { getenv(name) }
15
}

上面的 abs 被标记为 safe，是因为它对任意 i32 都满足 C 侧契约；getenv 仍保持 unsafe，因为调用者要保证参数是有效的 C 字符串，并处理返回指针的生命周期与线程安全。

这是我最赞同的变更之一。在 2021 及之前，extern "C" block 本身看不出是否有 FFI 安全契约；2024 Edition 把整个外部边界显式标成 unsafe extern，再允许开发者把少数确实安全的外部项标记为 safe。这样安全审查能一眼看到“边界在哪里、哪些函数仍需要调用者担保”。

迁移实操：cargo fix --edition 会自动在所有调用 extern 函数的地方包裹 unsafe {} 块。但要注意审查：自动插入的 unsafe 块范围可能过大，理想情况下应该把 unsafe 块缩到最小，并加上 Safety 注释：

1
fn read_env(name: *const std::ffi::c_char) -> *mut std::ffi::c_char {
2
    // SAFETY: name 由调用者保证为有效 C 字符串
3
    unsafe { getenv(name) }
4
}

4. if let / while let 临时变量作用域#

这是 2024 Edition 中对日常并发代码影响最大的变更。在 2021 edition 中，if let 或 while let 条件表达式产生的临时变量（如 MutexGuard）会存活到整个 if/else 块结束，极易引发死锁。

1
use std::sync::Mutex;
2

3
let mutex = Mutex::new(0);
4

5
// Edition 2021: MutexGuard 存活到 if 块结束
6
// 下面的代码会死锁——因为 guard 还活着，第二次 lock 会阻塞
7
if let Ok(guard) = mutex.lock() {
8
    // guard 在整个 if 块内都存活
9
    let _another = mutex.lock(); // ❌ 死锁！
10
}
11

12
// Edition 2024: 临时变量在模式匹配完成后立即 Drop
13
if let Ok(guard) = mutex.lock() {
14
    // guard 在进入分支前就 Drop 了
15
}
16
let _another = mutex.lock(); // ✅ 不会死锁

注意：如果你依赖旧行为（临时变量存活到块结束），迁移后可能出现编译错误或行为变化。常见场景是在 if let 分支内使用临时变量——需要将其绑定到局部变量：

1
// Edition 2024: 如果需要在分支内使用临时值，显式绑定
2
if let Some(value) = map.get(&key).cloned() {
3
    // value 是 Clone 出来的，不持有引用
4
}

5. 尾表达式临时变量 Drop 顺序#

2024 Edition 调整了块尾表达式（tail expression）产生的临时变量的 Drop 顺序。旧规则下，尾表达式的临时变量存活到下一个临时作用域结束（在局部变量 Drop 之后），新规则下临时变量提前 Drop，与局部变量的 Drop 顺序对齐。

1
// Edition 2021: 临时变量延迟 Drop，可能导致借用检查报错
2
fn old_example(c: &RefCell<Vec<i32>>) -> usize {
3
    c.borrow().len()  // borrow 产生的 Ref 持续到函数结束
4
}
5

6
// Edition 2024: 临时变量提前 Drop，借用更早释放
7
fn new_example(c: &RefCell<Vec<i32>>) -> usize {
8
    c.borrow().len()  // Ref 在表达式求值后立即 Drop
9
}

6. Never Type (!) 回退规则#

RFC 3550 调整了 Never Type 的类型推导回退规则。在 2021 edition 中，未明确类型的 ! 默认回退为 ()（Unit Type）；2024 edition 中默认回退为 ! 本身，使类型推导更严谨。

1
// Edition 2021: ! 回退为 ()
2
let result: _ = return;  // 推导为 ()
3

4
// Edition 2024: ! 回退为 !
5
let result: _ = return;  // 推导为 !

相关 lint 已升级为 deny，如果你的代码依赖旧回退行为，迁移时需要显式标注类型。

7. Match Ergonomics 限制#

2024 Edition 对 match ergonomics 做了收紧：不再允许在隐式解引用的模式中使用 ref、mut、ref mut 捕获修饰符。

1
// Edition 2021: 隐式解引用 + ref，行为难以预测
2
let x: &Option<i32> = &Some(42);
3
match x {
4
    Some(ref v) => println!("{}", v),  // ✅ 但语义令人困惑
5
    None => {}
6
}
7

8
// Edition 2024: 非显式模式中使用 ref 将报错
9
match x {
10
    Some(ref v) => println!("{}", v),  // ❌ error
11
    None => {}
12
}
13

14
// 修复：使用显式模式
15
match x {
16
    &Some(ref v) => println!("{}", v),  // ✅ 显式解引用
17
    &None => {}
18
}

8. match 穿透语义变更#

RFC 3516 改变了 match 中 || 模式的穿透（or-pattern）行为。在 2021 edition 中，| 模式在 match arm 中被视为整体，而 2024 edition 对其做了更精确的语义调整。

具体来说，在 2024 edition 中，match 的 | 模式不再允许在 arm 的模式一侧包含不可反驳（irrefutable）的子模式。这个变更主要影响的是一些边界情况，日常代码受影响较小：

1
// Edition 2024 中更严格的 or-pattern 规则
2
// 之前某些边缘写法会报错，需要调整模式结构
3
match value {
4
    Some(1) | Some(2) => println!("one or two"),
5
    _ => println!("other"),
6
}
7
// 这种常规写法在 2024 edition 中不受影响

经验谈：这个变更对日常代码影响较小，但它反映了 Rust 持续收紧模式匹配语义的趋势——让边界行为更可预测。

9. unsafe_op_in_unsafe_fn lint 升级#

2024 Edition 中 unsafe_op_in_unsafe_fn lint 默认升级为 warn（未来将 deny），要求在 unsafe fn 体内显式使用 unsafe {} 块来执行 unsafe 操作。这是 RFC 2585 的延续，目标是缩小 unsafe 的作用范围，让安全论证更精确。

1
// Edition 2021: unsafe fn 体隐式 unsafe
2
unsafe fn do_stuff(ptr: *const i32) -> i32 {
3
    *ptr  // 隐式 unsafe
4
}
5

6
// Edition 2024: 需要显式 unsafe 块
7
unsafe fn do_stuff(ptr: *const i32) -> i32 {
8
    // SAFETY: 调用者保证 ptr 有效且对齐
9
    unsafe { *ptr }
10
}

cargo fix --edition 会自动在 unsafe fn 体内的 unsafe 操作外包裹 unsafe {}，但建议审查并缩小 unsafe 块范围。

10. unsafe 属性（Attributes）#

2024 Edition 中，#[no_mangle]、#[export_name] 等属性必须显式标记为 unsafe，如 #[unsafe(no_mangle)]。

1
// Edition 2021
2
#[no_mangle]
3
fn my_exported_fn() {}
4

5
// Edition 2024
6
#[unsafe(no_mangle)]
7
fn my_exported_fn() {}

这防止了意外的链接冲突或内存段错误，明确标识了这些属性的不安全性质。

11. 禁止 static mut 引用#

获取 static mut 的引用在 2021 edition 中仅触发警告，2024 edition 中变为 Hard Error。

1
static mut COUNTER: i32 = 0;
2

3
// Edition 2021: 警告
4
// Edition 2024: 编译错误
5
// let ref_to_static = unsafe { &COUNTER };  // ❌ Hard Error
6

7
// 修复：使用 UnsafeCell 或原子类型
8
use std::sync::atomic::{AtomicI32, Ordering};
9
static COUNTER: AtomicI32 = AtomicI32::new(0);
10
let val = COUNTER.load(Ordering::SeqCst);  // ✅

12. 缺失宏片段说明符硬错误化#

missing_fragment_specifier lint 在 2024 Edition 中升级为 Hard Error。macro_rules! 中未使用的 arm 如果包含没有片段说明符的元变量（如 ($name) 而非 ($name:expr)），将直接报错而非警告。

1
// Edition 2021: 警告
2
macro_rules! bad_macro {
3
    ($name) => { ... };  // ⚠️ 缺少片段说明符
4
}
5

6
// Edition 2024: 编译错误
7
macro_rules! bad_macro {
8
    ($name) => { ... };  // ❌ Hard Error
9
}
10

11
// 修复：为所有元变量添加说明符
12
macro_rules! good_macro {
13
    ($name:expr) => { ... };  // ✅
14
}

注意：这与第14项”宏片段 :expr 变更”是不同的变更——:expr 变更是匹配范围的扩展，此项是缺失说明符的硬错误化。

13. macro_rules! 可见性变更#

2024 edition 中 macro_rules! 定义的宏不再自动在 crate 根可见，需要用 use 显式导入。

1
// Edition 2021: 自动 crate 根可见
2
macro_rules! my_macro { ... }
3
// 其他模块可以直接使用 my_macro!
4

5
// Edition 2024: 需显式 use
6
use crate::my_macro;

14. 宏片段说明符 :expr 变更#

2024 Edition 中 :expr 宏片段现在可以匹配 _ 和 const 块。如需保持旧行为，使用新增的 :expr_2021。

1
macro_rules! m {
2
    ($e:expr) => { ... };
3
}
4
// Edition 2021: m(_) 和 m(const { 1 }) 不匹配
5
// Edition 2024: m(_) 和 m(const { 1 }) 匹配

15. Prelude 扩充#

2024 Edition 将 Future 和 IntoFuture 加入 Prelude，编写异步代码无需再手动 use std::future::Future;。

1
// Edition 2021: 需要 use
2
use std::future::Future;
3
async fn foo() {}
4

5
// Edition 2024: 无需 use，Future 已在 Prelude 中
6
async fn foo() {}

16. Box<[T]> 的 IntoIterator#

2024 Edition 中 Box<[T]> 直接实现 IntoIterator，消耗 Box 并迭代出所有权值（T），行为与 Vec<T> 一致。旧 edition 中 .into_iter() 会隐式解引用为 &[T]，迭代出引用（&T）。

1
let boxed: Box<[i32]> = Box::new([1, 2, 3]);
2

3
// Edition 2021: into_iter() 迭代出 &i32
4
// Edition 2024: into_iter() 迭代出 i32，Box 被消耗
5
for val in boxed.into_iter() {
6
    // val: i32 (2024) vs &i32 (2021)
7
}

17. 环境变量操作变为 unsafe#

std::env::set_var 和 remove_var 在 2024 Edition 中变为 unsafe 函数，明确其在多线程/POSIX 环境下的不安全本质。

1
// Edition 2021: 安全函数
2
std::env::set_var("KEY", "VALUE");
3

4
// Edition 2024: unsafe 函数
5
unsafe { std::env::set_var("KEY", "VALUE"); }
6
// SAFETY: 单线程环境下调用，无并发写入

CommandExt::before_exec 也正式标记为 unsafe，建议使用安全的 pre_exec 替代。

18. 新 Range 类型（Rust 1.96.0 稳定化）#

RFC 3550 引入了新的 core::range::Range、RangeFrom、RangeInclusive 等类型，解决了旧 range 类型长期存在的一个设计问题：旧 range 类型实现了 Iterator，因此不能是 Copy。新 range 类型改为实现 IntoIterator（而非 Iterator），从而可以是 Copy，这消除了大量隐式 .clone() 的需要。

1
use core::range::Range;
2

3
// 新 range 类型：Copy + IntoIterator
4
let r: Range<i32> = 0..10;
5
let _r2 = r; // ✅ Copy，不需要 clone
6
for i in r {  // ✅ IntoIterator，可以迭代
7
    println!("{}", i);
8
}
9

10
// 旧 range 类型：Iterator 但非 Copy
11
let old_r: std::ops::Range<i32> = 0..10;
12
// let _old_r2 = old_r;  // ❌ 移动语义，old_r 已被消耗

未来 edition 中的语法变更：在未来的 edition 中，0..1 语法将产生新的 core::range::Range 类型，而非旧类型。旧 range 类型将移至 core::range::legacy::*，供迁移使用。

1
// 当前 edition：0..10 产生 std::ops::Range<i32>
2
// 未来 edition：0..10 产生 core::range::Range<i32>
3

4
// 迁移路径：如需旧类型语义
5
use core::range::legacy::Range as LegacyRange;
6
let old: LegacyRange<i32> = 0..10;

经验谈：新 range 类型是最值得注意的”静默改进”——大多数代码无需修改即可受益于 Copy 语义，但如果你的代码依赖 range 的 Iterator impl（而非 IntoIterator），需要注意类型变更。

重要说明：当前 0..1 语法仍然产生 legacy 类型（std::ops::Range），将在未来 Edition 中切换为 core::range::Range。core::range::RangeInclusive 的字段现在是 public（legacy 版本的字段是私有的）。库作者建议：在公共 API 中使用 impl RangeBounds 以同时兼容新旧类型。

19. assert_matches! / debug_assert_matches! 宏（Rust 1.96.0 稳定化）#

Rust 1.96.0 稳定了 assert_matches! 和 debug_assert_matches! 宏，本质上等同于 assert!(matches!(..))，但失败时打印值的 Debug 表示，更易诊断。

1
use core::assert_matches;
2

3
assert_matches!(value, Some(42));  // 失败时打印 value 的 Debug 表示
4
debug_assert_matches!(value, Some(42));  // 仅在 debug 模式检查

注意：未加入 prelude（避免与第三方 crate 冲突），需手动 use。

20. Cargo：MSRV 感知解析器 (Resolver v3)#

2024 Edition 默认启用 Resolver v3，自动过滤掉不兼容当前 MSRV（Minimum Supported Rust Version）的依赖版本。

1
rust-version = "1.80.0"
2
# 2021: 可能拉取需要 1.85 的依赖，导致编译失败
3
# 2024: 自动跳过不兼容版本，拉取符合 MSRV 的版本

这彻底解决了”更新依赖后老版本编译器无法编译”的痛点。

21. Cargo：Cargo.toml 键名一致性#

2024 Edition 强制要求所有 Cargo.toml 键名使用 kebab-case（如 default-features），不再允许 snake_case（如 default_features）。cargo fix 会自动修复。

22. Cargo：拒绝无效的 default-features#

对继承的依赖禁用 default-features 在 2021 edition 中不会报错但实际无效，2024 edition 中变为 Hard Error。这修复了配置中的逻辑错误（Rust 特性是加法的）。

23. 文档测试合并编译#

2024 Edition 尽可能将 doctests 合并到一个二进制文件中编译，cargo test --doc 性能获得数量级提升。

24. 嵌套 include! 相对路径#

include! 宏的相对路径解析从”相对于原始源文件”改为”相对于被包含的文档”（如 README.md），修复了文档中包含代码示例时引用外部资源的路径问题。

25. Rustfmt 变更#

2024 Edition 对 rustfmt 引入了多项变更：

a. style_edition：引入独立的样式版本，允许代码升级但保持旧版格式化风格，减少代码审查中的格式化噪音。

b. 版本排序：排序规则从纯字典序改为版本排序（数字按数值排序），更符合人类直觉。例如 NonZeroU8 现在排在 NonZeroU16 前面。

c. 原始标识符排序：rustfmt 排序时不再使用 r# 前缀作为排序键，而是使用原始标识符本身的名称。例如 r#async 按 async 的字母顺序排列。

d. 格式化修复（十余项）：2024 style edition 包含大量格式化修复，主要包括：

• 不再对齐无关的尾随注释
• 长字符串不再阻止表达式格式化
• 修复 impl 块中泛型缩进
• 去除嵌套元组索引多余空格（.0 .0 → .0.0）
• match 中 block 内的 return/break/continue 末尾加分号
• 宏调用与函数调用格式一致
• where 子句中空行移除
• let-else 带属性的格式修复