使用 Bun

有关将 Bun 与 Expo 和 EAS 结合使用的指南。

Bun 是一个 JavaScript 运行时，也是 Node.js 的替代品。在 Expo 项目中，Bun 可用于安装 npm 包并运行 Node.js 脚本。使用 Bun 的好处是比 npm、pnpm 或 Yarn 和 与 Node.js 相比，启动时间至少快 4 倍 更快的软件包安装，这极大地提升了你的本地开发体验。

¥Bun is a JavaScript runtime and a drop-in alternative for Node.js. In Expo projects, Bun can be used to install npm packages and run Node.js scripts. The benefits of using Bun are faster package installation than npm, pnpm, or Yarn and at least 4x faster startup time compared to Node.js, which gives a huge boost to your local development experience.

先决条件

¥Prerequisites

要使用 Bun、在本地计算机上安装 Bun 创建新应用。

¥To create a new app using Bun, install Bun on your local machine.

与 Bun 一起启动一个新的 Expo 项目

¥Start a new Expo project with Bun

要创建新项目，请运行以下命令：

¥To create a new project, run the command:

你还可以使用 bun run 运行任何 package.json 脚本：

¥You can also run any package.json script with bun run:

要安装任何 Expo 库，你可以使用 bun expo install：

¥To install any Expo library, you can use bun expo install:

使用 Bun 进行 EAS 构建

¥Use Bun for EAS builds

EAS 根据代码库中的锁定文件决定使用哪个包管理器。如果你希望 EAS 使用 Bun，请在你的代码库中运行 bun install，这将创建一个 bun.lockb（Bun 锁文件）。只要此锁定文件位于你的代码库中，Bun 将用作你构建的包管理器。确保删除其他包管理器生成的所有锁定文件。

¥EAS decides which package manager to use based on the lockfile in your codebase. If you want EAS to use Bun, run bun install in your codebase which will create a bun.lockb (the Bun lockfile). As long as this lockfile is in your codebase, Bun will be used as the package manager for your builds. Make sure to delete any lockfiles generated by other package managers.

在 EAS 上自定义 Bun 版本

¥Customize Bun version on EAS

使用 EAS 时，默认情况下会安装 Bun。请参阅 Android 服务器镜像 和 iOS 服务器镜像，了解你的构建映像使用了哪个版本的 Bun。

¥Bun is installed by default when using EAS. See the Android server images and iOS server images to learn which version of Bun is used by your build's image.

要将 Bun 的确切版本 与 EAS 一起使用，请在构建配置文件的配置下在 eas.json 中添加版本号。例如，以下配置为 development 构建配置文件指定了 Bun 版本 1.0.0：

¥To use an exact version of Bun with EAS, add the version number in eas.json under the build profile's configuration. For example, the configuration below specifies Bun version 1.0.0 for the development build profile:

{
  "build": {
    "development": {
      "bun": "1.0.0"
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
}

可信依赖

¥Trusted dependencies

与其他包管理器不同，Bun 不会自动从已安装的库执行生命周期脚本，因为这被认为存在安全风险。但是，如果你要安装的包包含要运行的 postinstall 脚本，则必须通过将该库包含在 package.json 的 trustedDependencies 数组中来明确声明。

¥Unlike other package managers, Bun does not automatically execute lifecycle scripts from installed libraries, as this is considered a security risk. However, if a package you are installing has a postinstall script that you want to run, you have to explicitly state that by including that library in your trustedDependencies array in your package.json.

例如，如果你安装 packageA，它依赖于 packageB，而 packageB 有 postinstall 脚本，则必须在 trustedDependencies 中添加 packageB。

¥For example, if you install packageA, which has a dependency on packageB and packageB has a postinstall script, you must add packageB in your trustedDependencies.

要在 package.json 中添加可信依赖，请添加：

¥To add a trusted dependency in your package.json, add:

"trustedDependencies": ["your-dependency"]

然后，删除锁定文件并重新安装依赖：

¥Then, remove your lockfile and re-install the dependencies:

常见错误

¥Common errors

使用 Sentry 和 Bun 时 EAS 构建失败

¥EAS Build fails when using Sentry and Bun

如果你使用 sentry-expo 或 @sentry/react-native，则它们依赖于 @sentry/cli，后者会在构建期间将源映射更新到 Sentry。@sentry/cli 软件包有一个 postinstall 脚本，需要运行该脚本才能使 "上传源地图" 脚本可用。

¥If you're using sentry-expo or @sentry/react-native, these depend on @sentry/cli, which updates source maps to Sentry during your build. The @sentry/cli package has a postinstall script which needs to run for the "upload source maps" script to become available.

要解决此问题，请将 @sentry/cli 添加到 package.json 中的 可信依赖 数组中：

¥To fix this, add @sentry/cli to your trusted dependencies array in package.json:

"trustedDependencies": ["@sentry/cli"]