The Bevy Book

Appearance

附录 E：版本迁移方法论 ​

Bevy 大约每三到四个月发布一个 0.x 版本，每个版本都有破坏性变更。掌握迁移方法比死记 API 更重要。

迁移指南在哪里 ​

每次版本发布时，Bevy 官方会在 GitHub Release 页面提供迁移指南（Migration Guide）。地址：

https://bevyengine.org/learn/migration-guides/

或直接在 GitHub 仓库的 release-content/ 目录下找到对应的 markdown 文件。

迁移指南的结构 ​

每条迁移条目通常包含：

  1. 标题：被修改的 API 或功能
  2. 影响范围：哪些代码会编译失败
  3. 迁移方式：新旧 API 的对照
  4. 原因：为什么做这个改动（可选）

迁移步骤 ​

1. 升级 Cargo.toml ​

toml
[dependencies]
bevy = "=0.19"  # 从 0.18.1 升到 0.19

2. 尝试编译 ​

console
cargo check 2>&1 | tee errors.txt

编译错误是最直接的迁移指引——每一个错误都对应一个 API 变更。

3. 按错误逐个修复 ​

  • 先修高频错误（如类型改名、trait 方法签名变更）
  • 再修低频错误（如 feature 名变更、模块路径调整）
  • 最后处理弃用警告（#[deprecated]）

4. 查阅迁移指南 ​

对于编译错误无法直接看出意图的变更，查阅迁移指南了解新旧对照。

5. 运行测试 ​

console
cargo test
cargo run  # 手动验证运行时行为

常见变更类型 ​

变更类型示例迁移方式
类型改名TransformBundle → 删除直接用 Transform + GlobalTransform
方法改名.insert_bundle() → .insert()批量替换
模块移动bevy::prelude::* 导出变化补充导入
Feature 变更feature 名改了更新 Cargo.toml
行为变更默认值不同了检查运行时输出
新增必选字段组件加了新字段补充字段或用 ..default()

工具辅助 ​

  • cargo fix：cargo fix --edition 可以自动修复部分弃用警告
  • 全局搜索：rg "old_api_name" 找到所有需要修改的位置
  • AI 辅助：让 AI 阅读迁移指南并生成替换建议（但要验证）

Bevy 0.19 计划 ​

截至本书编写时（Bevy 0.18.1），0.19 处于 RC 阶段。主要变更方向：

  • 编辑器原型的进一步推进
  • 渲染管线的持续优化
  • ECS 性能改进
  • 更多的内置 UI 控件

正式发布后，本书会提供全书迁移的详细指南。在此之前，建议保持 0.18.1 锁定。

给读者的建议 ​

  • 不要急着升级——新版本发布后等一到两周，让社区先踩坑
  • 锁定精确版本——bevy = "=0.18.1" 而不是 bevy = "0.18"
  • 会查源码——API 文档可能滞后，源码永远是最新版
  • 看官方示例——vendor/bevy/examples/ 是最可靠的行为参考