bevy-migration-0-18-to-0-19

Bevy 0.18 → 0.19 迁移

Bevy 0.19.0 于 2026-06-19 发布。将目标版本设为 bevy = "0.19"，并根据最新的 0.19 补丁版本进行验证。从头到尾应用官方迁移指南；本指南优先介绍最可能影响游戏代码和相关技能的变更。

首轮检查清单

1. 同时更新引擎和所有 Bevy 生态系统 crate。基于 Bevy 0.18 构建的 crate 无法与 Bevy 0.19 共用 ECS、资源或渲染类型。
2. 使用项目实际的 default-features 和目标平台三元组重新构建。
3. 优先解决资源和宽泛查询冲突，再处理次要的系统错误。
4. 更新场景、文本、资源、渲染、灯光和 UI 焦点。
5. 重新生成持久化的动画目标 ID 和序列化世界数据。
6. 编译有代表性的示例，并测试原生和 Web／平台构建。

影响较大的变更

Bevy 0.18	Bevy 0.19
#[derive(Component, Resource)]	拆分为不同类型；Resource: Component
宽泛查询加 Res<T>	适当时使用 Without<IsResource> 过滤资源实体
init_non_send_resource	init_non_send
SceneRoot / DynamicScene	WorldAssetRoot / DynamicWorld
bevy_scene 中旧版世界序列化	bevy_world_serialization
TextFont { font: Handle<_>, font_size: f32 }	FontSource 和 FontSize
TextLayout::new_with_justify	TextLayout::justify
LoadContext::loader()	LoadContext::load_builder()
使用 AsyncSeekForward 的自定义 Reader	必需的 Reader::seekable()
ViewNode 和相机渲染图节点	Core2d / Core3d 调度中的系统
Replace、on_replace	Discard、on_discard
set_executor_kind(ExecutorKind::...)	使用执行器实例的 set_executor(...)
灯光的 shadows_enabled	shadow_maps_enabled，以及可选的 contact_shadows_enabled
相机上的 Atmosphere	独立的 bevy::light::Atmosphere 实体
公共的 InputFocus.0	get、set 和 clear 方法

渲染节点 API 已移除，但名为 bevy::render::renderer::RenderGraph 的顶层非相机调度仍然存在。不要贸然替换这个调度名称。

文本和场景

TextFont {
    font: asset_server.load("fonts/FiraSans-Bold.ttf").into(),
    font_size: FontSize::Px(24.0),
    ..default()
}

commands.spawn(WorldAssetRoot(
    asset_server.load("models/level.glb#Scene0"),
));

现在由 Parley/fontique 提供文本整形和回退。发现已安装字体系列需要启用 system_font_discovery 功能。旧版序列化系统已重命名，以便为 BSN 腾出名称；glTF 根节点仍使用 WorldAssetRoot，而非 BSN 场景类型。

参见文本和字体和场景序列化。

资源和泛型查询

Res<T> 和 ResMut<T> 仍是常规 API。语义上的变化是，资源值现在存放在单例实体上，并且 #[derive(Resource)] 也会实现 Component。因此，宽泛的组件查询可能与资源访问冲突，也可能意外包含资源实体。

fn inspect_entities(
    entities: Query<EntityRef, Without<IsResource>>,
    settings: Res<GameSettings>,
) {
    // ...
}

不要机械地为每个查询都添加 Without<IsResource>；只收窄那些确实要检查普通实体的查询。参见作为组件的资源。

功能和生态系统 crate

[dependencies]
bevy = { version = "0.19", default-features = false, features = [
  "3d", "ui", "audio"
] }

• audio 不再由 2d、3d 或 ui 隐式启用。
• ui 不再由 2d 或 3d 隐式启用。
• Profile 集合必须与 default-features = false 搭配使用；否则 Cargo 的功能统一仍会启用默认功能。
• 禁用默认功能时，原生控制器事件需要 bevy_gilrs 后端。
• bevy_capture 0.6 和 bevy_hanabi 0.19 面向 Bevy 0.19。请核实其他每项依赖声明的 Bevy 版本，不要根据其 crate 版本猜测。

其他源代码迁移

• InputFocus 由 DefaultPlugins 初始化。在 Bevy 0.19.1 中，调用 focus.set(entity, FocusCause::Navigated)；单参数的 0.19.0 示例已过时。
• 重新计算序列化后的 AnimationTargetId 值：其哈希/ID 算法已更改。
• glTF 的 #Material0 标签现在返回 GltfMaterial；启用 PBR 转换时，追加 /std 以获取 Handle<StandardMaterial>。
• 高级加载现在通过 AssetServer::load_builder 进行；嵌套加载使用 LoadContext::load_builder。
• EasyScreenRecordPlugin 的手动字面量需要 output_dir；..default() 已提供该字段。
• FeathersPlugin 已更名为 FeathersCorePlugin，而 FeathersPlugins 仍是 插件组。

请参阅渲染、资源和 API。

验证迁移

cargo check --all-targets
cargo test
cargo tree -d | rg 'bevy(_| )'

将重复的 Bevy 主版本/次版本视为兼容性问题，而不是无害的 Cargo 噪声。此外，还要构建每种受支持的功能配置和目标；默认桌面构建无法验证 default-features = false 或 WASM。

另请参阅

• Bevy 官方迁移指南
• bevy-cargo-features
• bevy-rendering
• bevy-ui
• bevy-assets
• bevy-ecs-queries