了解如何在使用 React Native CLI 引导的项目中采用 Expo Prebuild。

---

使用 Expo 预建 至 不断生成你的原生项目 有 许多优点 个。本指南将向你展示如何在使用 npx react-native init 引导的项目中采用 Expo Prebuild。转换项目所需的时间取决于你对 Android 和 iOS 原生项目所做的自定义原生更改量。对于一个全新的项目，这可能需要一两分钟，而对于一个大型项目，时间会长得多。

¥There are many advantages of using Expo Prebuild to continuously generate your native projects. This guide will show you how to adopt Expo Prebuild in a project that was bootstrapped with npx react-native init. The amount of time it will take to convert your project depends on the amount of custom native changes that you have made to your Android and iOS native projects. This may take a minute or two on a brand new project, and on a large project, it will be much longer.

采用预构建将通过本地链接 expo-modules-core 自动添加对使用 Expo 原生模块 API 开发模块的支持。你还可以在项目中使用 Expo CLI 中的任何命令。

¥Adopting prebuild will automatically add support for developing modules with the Expo native module API by linking expo-modules-core natively. You can also use any command from Expo CLI in your project.

并非所有版本的 react-native 都得到明确支持。确保使用具有相应 Expo SDK 版本的 react-native 版本。

安装 expo 包

¥Install the expo package

expo 包包含 npx expo prebuild 命令并指示要使用哪个 预构建模板：

¥The expo package contains the npx expo prebuild command and indicates which prebuild template to use:

确保你安装的 expo 版本适用于当前安装的 react-native 版本。

¥Ensure you install the version of expo that works for your currently installed version of react-native.

更新入口文件

¥Update the entry file

修改入口文件以使用 registerRootComponent 而不是 AppRegistry.registerComponent：

¥Modify the entry file to use registerRootComponent instead of AppRegistry.registerComponent:

+ import {registerRootComponent} from 'expo';

- import {AppRegistry} from 'react-native';
import App from './App';
- import {name as appName} from './app.json';

- AppRegistry.registerComponent(appName, () => App);
+ registerRootComponent(App);

了解有关 registerRootComponent 的更多信息。

¥Learn more about registerRootComponent.

预建

¥Prebuild

确保你已提交更改，以防万一你想恢复，该命令也会警告你这一点！

如果你要迁移现有项目，那么你可能需要首先参考 迁移原生自定义。

¥If you're migrating an existing project, then you may want to refer to migrating native customizations first.

运行以下命令根据应用配置（app.json/app.config.js）配置重新生成 android 和 ios 目录：

¥Run the following command to regenerate the android and ios directories based on the app config (app.json/app.config.js) configuration:

你可以通过在本地构建项目来测试一切是否正常：

¥You can test that everything worked by building the projects locally:

了解有关 编译原生应用 的更多信息。

¥Learn more about compiling native apps.

额外的改变

¥Extra changes

以下更改是可选的，但建议进行。

¥The following changes are optional but recommended.

.gitignore

你可以将 .expo 添加到 .gitignore 以防止提交 Expo CLI 生成的值。这些 值对于你的项目来说是独一无二的 在你的本地计算机上。

¥You can add .expo to your .gitignore to prevent generated values from Expo CLI from being committed. These values are unique to your project on your local computer.

如果你想确保在预构建之间不会提交 android 和 ios，你还可以将 android 和 ios 添加到 .gitignore。

¥You can also add android and ios to the .gitignore if you want to ensure they are not committed between prebuilds.

app.json

删除顶层 expo 对象之外的所有字段，因为这些字段不会在 npx expo prebuild 中使用。

¥Remove all fields that are outside of the top-level expo object as these will not be used in npx expo prebuild.

{
-  "name": "myapp",
-  "displayName": "myapp"
+  "expo": {
+    "name": "myapp"
+  }
}

metro.config.js

参见 定制 Metro。

¥See Customizing Metro.

package.json

你可能想要更改脚本以使用 Expo CLI 运行命令：

¥You may want to change the scripts to use the Expo CLI run commands:

  "scripts": {
    "start": "expo start",
-    "android": "react-native run-android",
-    "ios": "react-native run-ios",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
  },

这些命令具有更好的日志记录、自动代码签名、更好的模拟器处理，并且它们确保你运行 npx expo start 来提供文件。

¥These commands have better logging, auto code signing, better simulator handling, and they ensure you run npx expo start to serve files.

迁移原生自定义

¥Migrate native customizations

如果你的项目有任何原生修改（对 android 或 ios 目录的更改，例如应用图标配置或启动屏幕），那么你需要配置应用配置 (app.json) 以反映这些原生更改。

¥If your project has any native modifications (changes to the android or ios directories, such as app icon configuration or splash screen) then you'll need to configure your app config (app.json) to reflect those native changes.

• 检查你的更改是否与内置 应用配置字段 重叠。例如，如果你有一个应用图标，请务必在 app.json 中将其定义为 expo.icon，然后重新运行 npx expo prebuild。

  ¥Check to see if your changes overlap with the built-in app config fields. For example, if you have an app icon, be sure to define it as expo.icon in the app.json then re-run npx expo prebuild.

• 查看你正在使用的任何软件包是否需要 Expo 配置插件。如果项目中的包需要在 android 或 ios 目录内进行其他更改，那么你可能需要一个配置插件。通过使用 package.json 依赖中的所有包运行 npx expo install 可以自动添加一些插件。如果某个软件包需要插件但不提供插件，那么你可以尝试检查 expo/config-plugins 上的社区插件，看看是否已经存在插件。

  ¥Look up if any of the packages you are using require an Expo config plugin. If a package in your project requires additional changes inside of the android or ios directories, then you will probably need a Config Plugin. Some plugins can be automatically added by running npx expo install with all of the packages in your package.json dependencies. If a package requires a plugin but doesn't supply one, then you can try checking the community plugins at expo/config-plugins to see if one already exists.

• 你可以使用 VS Code Expo 扩展 内省你的更改并调试预构建是否生成你期望的原生代码。只需按 Cmd ⌘ + Shift + p，输入“Expo:预览修改器”，然后选择你想要内省的原生文件。

  ¥You can use the VS Code Expo extension to introspect your changes and debug if prebuild is generating the native code you expect. Just press Cmd ⌘ + Shift + p, type "Expo: Preview Modifier", and select the native file you wish to introspect.

• 此外，你可以开发本地配置插件来满足你的需求。了解更多。

  ¥Additionally, you can develop local config plugins to fit your needs. Learn more.

添加更多功能

¥Add more features

预构建是自动化的冰山一角，以下是你接下来可以采用的一些功能：

¥Prebuild is the tip of the automation iceberg, here are some features you can adopt next:

• EAS 构建：代码签名和云构建。

  ¥EAS Build: Code signing and cloud building.

• EAS 更新：立即发送无线更新。

  ¥EAS Update: Send over-the-air updates instantly.

• 用于 Web 的 Expo：在浏览器中运行你的应用。

  ¥Expo for web: Run your app in the browser.

• Expo 开发客户端：围绕你的原生运行时创建你自己的个人 "Expo" 类型应用。

  ¥Expo Dev Client: Create your own personal "Expo Go" type app around your native runtime.

• Expo 原生模块 API：使用 Swift 和 Kotlin 编写模块。使用 npx expo prebuild 时会自动支持此功能。

  ¥Expo native module API: Write modules with Swift and Kotlin. This is automatically supported when using npx expo prebuild.