奇怪的编译错误

有时，当你试图编译你的项目时，你会遇到奇怪的、令人困惑的编译错误，下面提供一些有用的解决方法。

更新你的 Rust

首先，确保你的 Rust 是最新的。当使用 Bevy 时，你必须至少使用最新的稳定版 Rust（或者 nightly 版本）。

如果你正在使用 rustup 来管理你的 Rust 安装与升级，你可以运行：

rustup update

重置 cargo 状态

许多类型的构建错误通常可以通过强制 cargo 重新生成它的内部状态（重新计算依赖关系等）来解决。你可以通过删除 Cargo.lock 文件和 target 目录来做到这一点。

rm -rf target Cargo.lock

这样做之后，再试着构建你的项目，很可能那些神秘的错误就会消失。

这一招通常能解决构建失败的问题，但你的问题仍未能解决，那你的问题可能需要进一步的调查。可以通过 GitHub 或 Discord，在 Bevy 社区中寻求帮助。

如果你使用的是 Bevy main 开发分支，而上述方法又未能解决你的问题，那你的错误可能是由第三方插件引起的。请看这个页面的解决方案。

新的 Cargo Resolver

Cargo 最近增加了一种新的依赖性解析算法，与旧的算法不兼容。Bevy 需要 新的解析器。

如果你只是创建一个新的空白 Cargo 项目，不用担心，cargo new 已经处理好了相关的配置。

如果你从 Bevy 的依赖关系中得到奇怪的编译器错误，请继续阅读下面的内容，确保你的配置正确，然后 重置 cargo 状态。

Single-Crate Projects

在包含单个库的项目中（你的项目中只有一个 Cargo.toml 文件），如果你使用最新的 Rust2021 版本，新的解析器会自动启用。

所以，在下面两种示例配置中，任选一种用来配置你的 Cargo.toml，

使用 Rust2021 版本情况配置如下：

[package]
edition = "2021"

或，使用低于 Rust2021 版本则配置如下：

[package]
resolver = "2"

Multi-Crate Workspaces

在包含多个库的 Workspaces 中，解析器是整个工作区的一个全局设置。默认情况下，它 不会 被启用。

如果你正在将一个单库项目过渡到一个 Workspace，你或许会被坑到。

你 必须 在你的 Cargo Workspace 的顶级 Cargo.toml 中手动添加解析器的版本配置：

[workspace]
resolver = "2"

什么样的错误？

一个常见的例子是 "failed to select a version" 的错误，它可能看起来像这样：

error: failed to select a version for `web-sys`.
    ... required by package `wgpu v0.9.0`
    ... which is depended on by `bevy_wgpu v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_internal v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy-scratchpad v0.1.0 (C:\Users\Alice\Documents\bevy-scratchpad)`
versions that meet the requirements `=0.3.50` are: 0.3.50

all possible versions conflict with previously selected packages.

  previously selected package `web-sys v0.3.46`
    ... which is depended on by `bevy_app v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_asset v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_audio v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_internal v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy-scratchpad v0.1.0 (C:\Users\Alice\Documents\bevy-scratchpad)`

failed to select a version for `web-sys` which could resolve this conflict

(依据具体情况，你的可能和上面的例子不完全一样)

相关的另一个看似无意义的编译器错误提示，是与 Bevy 的内部类型产生冲突（如 "expected type Transform, found type Transform"）。

为什么会这样？

这类错误通常是由于 cargo 的内部状态被破坏而引起的。因为依赖关系没有被正确解决，导致 cargo 试图将多个版本的 Bevy 链接到你的项目中。这种情况经常发生于你在你的项目中切换使用 Bevy 发布版本和 git 版本，但 Cargo 仍会记住它之前使用的版本，并因此遭遇困惑。

关于这个 bug，请看这个 cargo issue。如果你有任何有趣的信息要补充，你可以在该问题下贡献你的帮助。