使用 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%%
  }
}

从 npm、pnpm 或 yarn 迁移到使用 Bun

¥Migrate to using Bun from npm, pnpm or yarn

目前无法将另一个包管理器的锁定文件导入到 Bun 中（尽管此功能正在 从事 中）。在此之前，在现有项目上切换到 Bun 会存在风险。

¥It is currently not possible to import another package manager's lockfile into Bun (though this feature is being worked on). Until this is done, there is an element of risk to switching over to Bun on an existing project.

锁定文件的目的是锁定你的依赖树。如果 package.json 中有一个版本号以 ^ 或 ~ 开头的库，你可能最终会得到不同版本的包。

¥The purpose of a lockfile is to lock down your dependency tree. If there is a library in package.json whose version number starts with a ^ or ~, you are likely to end up with a different version of the package.

• ^ 意味着你选择未来的次要版本和补丁版本

  ¥^ means you're opting into future minor and patch versions

• ~ 表示你仅选择未来的补丁版本

  ¥~ means you're opting into future patch versions only

根据语义版本控制 (SemVer)，次要版本和补丁版本不包含重大更改。不幸的是，重大变化仍然可能会被忽视。由于锁定文件包含特定版本的依赖，因此除非你明确选择加入，否则你将不会获得更新。通过删除锁定文件，你将失去安全性并获得 package.json 中定义的所有包的最新可用版本。

¥According to Semantic Versioning (SemVer), minor and patch versions do not include breaking changes. Unfortunately, breaking changes can still slip through. Since a lockdown file contains specific versions of dependencies, you will not get updates unless you explicitly opt-in. By deleting the lockfile, you are losing that safety and getting the latest versions available of all the packages as defined in your package.json.

要迁移到使用 Bun（使用风险自负）：

¥To migrate to using Bun (use at your own risk):

可信依赖

¥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"]