SyncComponentPlugin

SyncComponentPlugin<T> 是 Bevy 渲染架构中的关键机制，负责将主世界（Main World）中组件的变更同步到渲染世界（Render World）。

核心概念

Bevy 的渲染管线基于双世界架构：

• Main World：用户代码操作的 ECS 世界（组件添加/修改/移除）
• Render World：GPU 渲染管线的 ECS 世界（提取后的数据副本）

SyncComponentPlugin<T> 做的事情：监听主世界中组件 T 的变更（插入/修改/移除），并将这些变更镜像到渲染世界中对应的实体。

何时自动注册

当组件通过 ExtractComponentPlugin 实现采掘时，SyncComponentPlugin 会被自动注册。ExtractComponentPlugin 的默认实现在内部调用了 SyncComponentPlugin。

何时需要手动注册

当组件没有通过 ExtractComponentPlugin 采掘时，必须手动注册 SyncComponentPlugin。 典型场景：

1. Orphan rule 限制： 组件的 ExtractComponent 实现在另一个 crate 中，无法直接使用 ExtractComponentPlugin（孤儿规则限制）
2. 手动采掘逻辑： 采掘通过自定义系统实现，而非 ExtractComponentPlugin 的 trait 接口

实际案例：Skybox 迁移 bug

PR #22682 将 Skybox 从 bevy_pbr 迁移至 bevy_light 时，因 orphan rule 限制，采掘从 ExtractComponentPlugin 改为手动实现。但迁移过程中遗漏了 SyncComponentPlugin<Skybox> 的手动注册。

后果：

• 添加 Skybox 组件时正常工作（手动采掘逻辑仍有效）
• 但移除 Skybox 时，渲染世界中的拷贝不会同步删除
• 导致天空盒在组件移除后仍渲染

PR #24389 修复：添加一行手动注册 app.add_plugins(SyncComponentPlugin::<Skybox>::default())。

设计教训

SyncComponentPlugin 的「自动注册」依赖于 ExtractComponentPlugin 这条路径。一旦脱离这条路径（如 orphan rule、手动采掘），sync 的责任就落到开发者身上，而这是静默且容易遗漏的——编译不会报错，运行时也不崩溃，只是渲染世界状态不一致。

检查清单：

• 如果组件实现了 ExtractComponent trait，确认采掘路径是否通过 ExtractComponentPlugin
• 如果不是通过 ExtractComponentPlugin，确认已手动注册 SyncComponentPlugin<T>
• 验证方式：添加组件→移除组件→确认渲染世界无残留（如 anisotropy 示例切换测试）

相关页面

• skybox — Skybox 组件实体页面（本 bug 的实际案例）
• bevy-rendering — Bevy 渲染系统总览
• bevy — Bevy 引擎实体总览
• bevy-game-dev-2026-05 — 2026 年 5 月引擎变更追踪