Rust 2024 Edition 怎样准备项目迁移

Rust 2024 Edition 迁移应先在旧 Edition 下运行兼容修复，再修改清单中的 edition，最后覆盖项目实际使用的功能和平台。我的建议是把依赖更新、语言迁移和格式调整拆成独立提交，尤其别把自动补上的 unsafe 当成安全问题已经解决。

官方迁移指南：https://doc.rust-lang.org/edition-guide/rust-2024/

Rust 2024 随 Rust 1.85.0 于 2025 年 2 月 20 日稳定发布。这是已发布能力的迁移准备说明，不是新的版本快讯。Edition 表达一组选择启用的语言兼容规则，并不是每年都要修改的年份标签。

先保护可以回退的构建基线

面对一个已经上线的 2021 项目，我会先保留当前提交、Cargo.lock、工具链版本、构建参数和发布产物。这样发生问题时，恢复对象明确，避免只把 edition 改回去却留下依赖和源码变化。这是工程安排建议，本文没有声称已经在某个生产项目完成迁移。

先确认开发机、CI 和交叉编译环境都使用支持 2024 的工具链，1.85 是支持该 Edition 的起点，不意味着所有依赖都只需要这个最低版本。库作者还应区分 edition 与 rust-version：前者选择语言规则，后者声明最低 Rust 版本要求；不能只改前者就承诺下游兼容。

把依赖变化与语言变化分开

官方建议迁移前更新依赖，尤其留意过程宏和构建时代码生成器。我倾向于先在独立分支评估更新后的锁文件，把依赖更新单独提交，再进入 Edition 修改。不要为迁移顺手升级所有不相关的大版本，也不要把锁文件差异隐藏在格式化提交里。

工作区按包确认 edition 配置及继承关系，不要认为改一个 Cargo.toml 就覆盖所有成员。不同 Edition 的 crate 可以互相依赖，通常可以按成员分批迁移，而不用强迫整个依赖树同时切换。

在旧 Edition 下运行兼容修复

下面是供读者在干净迁移分支使用的命令示例，本文没有执行这些命令。先保留原来的 edition 配置，再让 Cargo 应用兼容建议：

# 查看工具链，记录到迁移说明中
rustc --version
cargo --version

# 在干净的版本控制工作区执行；此时清单仍保持旧 Edition
cargo fix --edition --workspace

# 查看自动修改，避免把未理解的变化直接提交
git diff

cargo fix 不会替你修改 edition 字段。它只能处理本轮编译配置实际启用的代码：默认功能之外的可选分支、其他目标平台的 cfg 分支，都需要按项目支持矩阵分别安排。只有功能可以同时启用时才考虑 --all-features；互斥功能要使用各自合法组合，不能机械拼在一起。

自动改写之外，优先处理共享状态

迁移里的高风险点是把“能编译”误当成“安全前提成立”。例如 std::env::set_var 与 remove_var 在 2024 中需要 unsafe；兼容修复可以加上代码块，却无法证明线程相关前提。全局环境若被多个线程或依赖访问，添加一个 unsafe 并不会消除风险。

我的取舍是：服务运行中的可变业务配置优先用显式配置对象传递；若只是为子进程设置环境，考虑通过 Command 的子进程环境配置传入，而不是改整个父进程的环境。确实需要调用这些函数时，必须根据具体平台的官方 Safety 要求说明前提，不能用“只有初始化时调用”一句话代替证明。

同时给宏、生成代码和文档示例分配负责人。自动修复无法保证它们都被覆盖；其余语言语义变化应按迁移指南逐项映射到本项目，避免把官方变更清单当作已完成记录。

修改清单后，保留能够复查的记录

兼容改写处理完后，在实际包的 [package] 中修改或继承正确的 Edition。下面是 TOML 片段，不是完整清单：

[package]
# 在已有包清单里修改此字段，保留原来的名称和依赖
edition = "2024"

随后由项目维护者执行正常构建和回归，覆盖使用中的目标、功能组合、集成测试及文档示例。格式化最好另开提交，避免掩盖语义修改。出现未覆盖的平台或尚未解释的 unsafe 前提时，记录阻塞项，不要为了统一年份仓促推进。

常见疑问

升级编译器会自动切换 Edition 吗？不会。已有项目以清单配置为准，更新工具链与选择 Edition 是两项操作。

cargo fix 没报错就可以结束吗？不能据此推断项目所有配置都已覆盖，也不能据此判断共享状态的安全条件。它解决的是可自动应用的编译器建议。

哪些项目适合先迁移？依赖维护活跃、支持平台明确、回归资料齐全的成员适合先做；旧过程宏、复杂条件编译或发布链缺乏可回退产物的项目，应先补齐这些准备。

我的判断是，迁移价值在于让新规则与现有工程契约接上，而不在于把年份改得更整齐。独立提交、明确责任和可恢复基线，会让这次变更更容易交接。

参考：Rust 1.85 与 2024 发布公告；已有项目迁移指南；Cargo fix 文档；新增 unsafe 要求。