深入解析 Bevy 错误 B0002：同一系统内资源访问冲突的成因、复现与修复-二趣网

深入解析 Bevy 错误 B0002：同一系统内资源访问冲突的成因、复现与修复

【免费下载链接】bevyA refreshingly simple>项目地址: https://gitcode.com/GitHub_Trending/be/bevy

本篇技术指南围绕 Bevy 错误码B0002展开，它是一类在调度器构建阶段就会以panic形式爆发的运行时错误，本质是系统参数之间的访问权限发生了冲突。文章会从触发场景、错误示例、修复方案一路深入到bevy_ecs的源码实现，并重点解释"资源即组件"这一设计给查询系统带来的隐性约束。读完本文，你将能够快速识别 B0002 的报错形态、理解其底层机制，并掌握用Without过滤、收敛查询等手段写出不冲突的系统。

B0002 是什么：同一系统中出现同一类资源的重复访问

错误码文档位于仓库的 errors/B0002.md，并由 errors/src/lib.rs 通过#[doc = include_str!("../B0002.md")]内嵌为B0002结构体的文档注释，最终以编译期文档形式随 Bevy 发布。同时该错误码的触发文案直接硬编码在 ECS 调度源码中，属于"运行到就会 panic"的硬错误，而非仅记录日志的警告。

根据官方错误码文档的解释，B0002 的产生根源是Rust 的借用规则：

同一个值要么同时存在任意多个不可变引用，要么只存在一个可变引用，二者不可兼得。

Bevy 系统在运行时通过UnsafeWorldCell获得对世界数据的访问权，为了让"同时只有一个可变引用"这一规则在 ECS 场景下同样成立，调度器要求：在同一个系统内，不允许同时出现对同一类资源的"可变 + 不可变"两种访问参数。典型表现有两类：

对同一个T，同时使用 [Res<T>] 与 [ResMut<T>]；
对同一个T，同时使用NonSend<T>与NonSendMut<T>。

其中Res/ResMut用于读取「线程安全、可在系统间并行共享」的资源，而NonSend/NonSendMut用于访问「非Send」的资源（只能由运行在单线程上的系统访问），它们的访问冲突规则是等价的。

注：本文不输出外部链接，文档原提到的Res/ResMut/NonSend/NonSendMut的完整签名均可直接在 crates/bevy_ecs/src/system/system_param.rs 中查阅到。

典型报错形态：ResMut 与 Res 同取一个资源

错误示例

以下系统试图在同一个函数参数列表里同时取得Assets<StandardMaterial>的可变与不可变访问：

use bevy::prelude::*; fn update_materials( mut material_updater: ResMut<Assets<StandardMaterial>>, current_materials: Res<Assets<StandardMaterial>>, ) { // ... } fn main() { App::new() .add_plugins(DefaultPlugins) .add_systems(Update, update_materials) .run(); }

运行到调度器构建该系统的阶段就会 panic——因为对同一个Assets<StandardMaterial>，系统既声明了写权限（ResMut）又声明了读权限（Res），违反了"一写多读不得同时声明可变与不可变"的规则。Bevy 宁可立刻崩溃也不允许在运行期出现数据竞争。

错误文本到底从哪里来

B0002 的 panic 文案在 crates/bevy_ecs/src/system/system_param.rs（Res）与 crates/bevy_ecs/src/system/system_param.rs（ResMut）中生成，形如：

error[B0002]: Res<Assets<StandardMaterial>> in system update_materials conflicts with a previous system parameter. Consider removing the duplicate access or using `Without<IsResource>` to create disjoint Queries or merging conflicting Queries into a `ParamSet`.

非Send数据的分支则在 crates/bevy_ecs/src/system/system_param.rs（NonSend）与同文件约 L1380 处（NonSendMut）各自生成独立的 B0002 panic。也就是说，只要你看到error[B0002]前缀，就可以立刻判定：系统参数之间注册的访问权限重叠了。

修复：直接删除只读参数

由于ResMut<T>本身已经包含了对当前值的读访问能力，同时保留Res<T>是纯属多余且非法的声明。正确做法是只保留可变引用：

use bevy::prelude::*; fn update_materials( mut material_updater: ResMut<Assets<StandardMaterial>>, ) { // ... } fn main() { App::new() .add_plugins(DefaultPlugins) .add_systems(Update, update_materials) .run(); }

修复后的系统功能与原来完全等价，因为ResMut解引用后同样可以读取资源的当前值。

进阶场景：资源即组件，Query 与 Res 的隐性冲突

如果 B0002 仅仅发生在同一类型Res/ResMut并存时，那它还只是"参数声明重复"的低级问题。真正容易让人困惑的是文档后半部分指出的一个更深层事实——在 Bevy ECS 的底层，资源本身就是组件。

从源码看"资源即组件"

这一设计并非文档的比喻，而是可以直接在源码中验证的实现事实：

crates/bevy_ecs/src/resource.rs 中定义了IsResource标记组件，注释明确写着"A marker component for entities that have a Resource component"（用于标记那些拥有 Resource 组件的实体）；
同一个文件中 crates/bevy_ecs/src/resource.rs 还导出了IS_RESOURCE常量，它指向IsResource这个组件的固定ComponentId；
每个资源都会被装到一个"资源实体"上，由ResourceCache（SparseArray<ComponentId, Entity>）维护"资源 → 持有它的实体"的映射，见 crates/bevy_ecs/src/resource.rs。

既然资源是某个实体上的组件，那么当你写出一个"查询所有实体"的系统时，它理所当然也会把持有资源的那个实体一并纳入——从而与Res/ResMut对该资源的访问发生重叠，触发 B0002。文档原文对此的表述是：

Under the hood, resourcesarecomponents.

这种后果平时只是实现细节，不会影响用户，但一旦出现下面这类系统就会报错：

use bevy::prelude::*; #[derive(Resource)] struct MyResource; fn system(all_entities: Query<EntityMut>, res: Res<MyResource>) {}

这里Query<EntityMut>表示"对世界里的每个实体都拥有独占（可变）访问权"，自然也包括了存放MyResource的那个实体，于是与Res<MyResource>的可变/不可变访问声明正面冲突。注意文档明确标注这是无法同时成立的组合，而不是偶发的运行序问题。

哪些查询会与 Res/ResMut 冲突

文档列出了所有可能踩坑的宽泛查询形态：

Query<()>
Query<Entity>
Query<EntityMut>
Query<EntityRef>
Query<EntityMutExcept>
Query<EntityRefExcept>
Query<Option<&T>>

它们的共同点是访问范围覆盖所有实体（EntityMutExcept/EntityRefExcept仅排除少数指定组件，其余实体仍全覆盖），因此必然扫过资源所在实体。对应的访问登记与冲突检测逻辑集中在 crates/bevy_ecs/src/query/access.rs 与 crates/bevy_ecs/src/query/world_query.rs 中的update_component_access一族方法里；而Res/ResMut在注册访问时会调用filter.and_with(IS_RESOURCE)把自己的作用域收窄到"带IsResource标记的实体"上（见 crates/bevy_ecs/src/system/system_param.rs），收窄之后仍与"全实体"查询发生交集，于是冲突被检测出来并触发 B0002 panic。

修复一：收敛查询范围

文档给出的第一类修复思路是"你通常并不需要真的查询每个实体"。请把Query<EntityMut>这类全量查询收敛为只针对你关心的组件集合，例如改为Query<(&mut Transform, &Visibility)>，让查询的访问集合只覆盖具体组件，从而绕开资源实体上的IsResource组件。

修复二：用 Without 显式排除资源

如果确实需要保持对实体集合的遍历，可以用过滤条件把资源实体剔除出去。这里有两个层次的过滤目标：

按资源类型排除：Without<MyResource>，把当前资源值所在实体排除在查询之外；
按资源标记统一排除：Without<IsResource>，一次性排除所有持有资源的实体。

官方推荐优先使用Without<IsResource>，因为正如文档所写，IsResource是"每一个持有资源的实体上"都带有的标记组件，用它来做全局排除非常省事。对应示例：

use bevy::prelude::*; #[derive(Resource)] struct MyResource; fn system( all_entities: Query<EntityMut, Without<IsResource>>, res: Res<MyResource>, ) {}

非 Send 数据的同类问题

同样的限制也适用于非Send资源。以下写法同样会 panic：

use bevy::prelude::*; #[derive(Resource)] struct MyNonSend; fn system(all_entities: Query<EntityMut>, some_non_send: NonSend<MyNonSend>) {}

修复方式与上文一致——因为非Send资源同样存储为实体组件，只需给查询加上Without<MyNonSend>过滤器即可：

fn system( all_entities: Query<EntityMut, Without<MyNonSend>>, some_non_send: NonSend<MyNonSend>, ) {}

B0002 的另外两个来源与源码佐证

除了文档重点讲解的Res/ResMut与全实体查询两类冲突，本仓库中还存在着其他能触发error[B0002]前缀的运行路径，一并列出可帮助你排查时快速对号入座：

对&mut World独占参数混入其他参数：require_exclusive_access会在系统已有共享或独占访问时直接 panic，文案同样是error[B0002]，见 crates/bevy_ecs/src/system/access.rs。例如系统同时声明&mut World与Query<&mut A>、Query<()>或Option<Query<&mut A>>等组合都会失败；
FilteredResources/FilteredResourcesMut：这类参数也以IS_RESOURCE过滤访问，与前置参数冲突时产生 B0002 panic，见 crates/bevy_ecs/src/system/system_param.rs。

仓库中的单测覆盖了上述形态，例如 crates/bevy_ecs/src/system/system_param.rs 中的mutable_world_conflicts_with_optional_query、mutable_world_conflicts_with_query、mutable_world_conflicts_with_empty_query等用例，均用#[should_panic(expected = "error[B0002]")]断言冲突系统必然以 B0002 文案崩溃。这些测试从侧面印证了 B0002 是 Bevy 有意为之的"宁可 panic 也不容忍数据竞争"策略。

排查清单与修复决策

当你拿到一段 B0002 报错时，可以按以下顺序定位并修复：

先看系统参数里是否有同一个T的Res<T>与ResMut<T>（或NonSend/NonSendMut）并存：若有，直接删除只读参数即可，因为可变参数天然具备读取能力；
再检查是否同时存在全实体查询：如Query<()>、Query<Entity>、Query<EntityMut>、Query<Option<&T>>等与Res/ResMut组合；若是，判断该查询是否真的需要遍历每一个实体，通常收敛为具体组件的查询即可；
若遍历确实必要，为查询添加Without<IsResource>：一句过滤即可与所有资源访问解耦；当只想排除某一种特定资源时，改用更精确的Without<MyResource>或Without<MyNonSend>；
若系统本身声明了&mut World这类独占访问，就不要再混入任何查询或资源参数，把独占逻辑拆成独立系统。

小结

B0002 是 Bevy ECS 保障内存安全的一道硬性防线：它把 Rust 的借用规则在"世界级"数据上强制执行，任何同一系统内对同一资源"可变 + 不可变"的重复声明、或全实体查询与资源访问的重叠，都会在调度器构建阶段以error[B0002]的 panic 快速失败。理解它的关键认知在于两点：其一，可变资源访问已蕴含读取，不要重复声明只读访问；其二，资源在底层就是实体上的组件，并由IsResource标记，因此宽泛查询需要用Without<IsResource>（或更精确的Without<T>）显式避开资源实体。把握住"访问集合是否重叠"这一核心，B0002 就不再是令人困惑的随机崩溃，而是一份可读性极强的约束说明书。

【免费下载链接】bevyA refreshingly simple>项目地址: https://gitcode.com/GitHub_Trending/be/bevy

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析