了解如何将自定义原生代码添加到你的 Expo 项目中。

---

Expo 项目可以使用带有原生代码的第三方 React Native 库和你自己的自定义原生代码。创建 开发构建 允许你包含特定的原生依赖和自定义，而不仅仅是最新 Expo SDK 附带的内容。这些原生自定义可以是任何 React Native 库或你自己的自定义原生代码。

¥Expo projects can use both third-party React Native libraries with native code and your own custom native code. Creating a development build allows you to include your specific native dependencies and customizations and not only what comes with the latest Expo SDK. These native customizations can be any React Native library or your own custom native code.

对于大多数第三方原生库，autolinking 使这一切变得简单。你所要做的就是安装 npm 包并运行 prebuild 以使用该模块。某些模块可能还需要 config-plugin 来进行其他原生自定义。添加你自己的自定义原生代码时，方法会根据你想要使用原生代码的方式而有所不同。

¥For most third-party native libraries, autolinking makes it easy. All you have to do is install the npm package and run prebuild to use the module. Some modules might also need a config-plugin for additional native customizations. When adding your own custom native code, the approach varies based on how you want to work with native code.

使用 Expo Modules API 创建本地模块

¥Create a local module with the Expo Modules API

默认情况下，Expo 项目使用 持续的原生生成 (CNG)。这意味着项目没有包含原生代码和配置的 android 和 ios 目录。相反，原生目录是在构建应用之前生成的，并且基于 package.json 中的 应用配置 和原生模块。这简化了原生代码的管理和升级。

¥By default, Expo projects use Continuous Native Generation (CNG). This means that projects do not have android and ios directories containing the native code and configuration. Instead, the native directories are generated right before building the app and are based on your app config and native modules in package.json. This simplifies the management and upgrading of native code.

你似乎无法使用 CNG 将自定义原生代码添加到项目中。但是，你仍然可以在 创建本地 Expo 模块 之前添加该内容。

¥It might seem you cannot add custom native code to a project using CNG. However, you can still add that by creating a local Expo module.

本地 Expo 模块的功能与库开发者在 Expo SDK 中使用的 Expo 模块 类似。它们不会发布到 npm。相反，你可以直接在项目中创建它们。

¥Local Expo Modules function similarly to Expo Modules used by library developers and within the Expo SDK. They are not published to npm. Instead, you create them directly inside your project.

创建本地模块允许你编写自定义 Swift 和 Kotlin 代码，你可以通过 JavaScript 代码与之交互。当你使用 EAS 构建 或 本地编译你的应用 构建时，它也会自动包含在开发构建和生产应用中。

¥Creating a local module allows you to write custom Swift and Kotlin code that you can interact with from your JavaScript code. It is also included in the development builds and production apps automatically when you build with EAS Build or when you compile your app locally.

管理自定义原生项目

¥Manage custom native projects

你可以选择退出 CNG 并直接管理 android 和 ios 目录中的代码和配置。要生成这些目录，请运行 npx expo prebuild 或 本地编译你的应用（npx expo run:android 或 npx expo run:ios）。你还可以在本地编译应用之前创建开发版本。为此，请在 prebuild 或 run 之前运行 npx expo install expo-dev-client。

¥You can opt out of CNG and directly manage the code and configuration inside your android and ios directories. To generate these directories, run npx expo prebuild or compile your app locally (npx expo run:android or npx expo run:ios). You can also create a development build before compiling your app locally. To do so, run npx expo install expo-dev-client before prebuild or run.

• npx expo run:android 需要安装 Android Studio 和 Android SDK。看看如何 设置环境。

  ¥npx expo run:android requires Android Studio and the Android SDK to be installed. See how to setup environment.

• npx expo run:ios 需要在你的计算机上安装 Xcode（仅限 macOS）。看看如何 设置环境。

  ¥npx expo run:ios requires Xcode (macOS only) installed on your computer. See how to setup environment.

run 命令将对你的项目进行 prebuild，以在项目目录中生成所有原生代码。如果你手动修改 android 或 ios 目录，则无法安全地重新运行 npx expo prebuild，因为这可能会覆盖你的更改。

¥The run commands will prebuild your project to generate all the native code within your project directory. If you manually modify the android or ios directory, you cannot re-run npx expo prebuild safely, as this may overwrite your changes.

如果你使用 Expo 配置插件 安装库，则需要执行以下几个步骤：

¥If you install a library with Expo config plugin, you'll need to follow a few steps:

• 将插件添加到项目应用配置中的 plugins 数组中。

  ¥Add the plugin to the plugins array in the project's app config.

• 在重建原生应用之前重新运行 npx expo prebuild 以同步更改。此过程通常涉及向 AndroidManifest.xml 或 Info.plist 添加所需权限等任务。

  ¥Re-run npx expo prebuild to sync the changes before rebuilding the native app. This process often involves tasks like adding required permissions to the AndroidManifest.xml or Info.plist.

• 对于复杂的插件，请考虑运行 npx expo prebuild --clean。此命令将从头开始删除并重新生成原生目录。

  ¥For complex plugins, consider running npx expo prebuild --clean. This command will delete and re-generate the native directories from scratch.

手动更改原生项目文件

¥Manual changes to the native project files

如果手动修改 android 和 ios 目录，则必须手动设置新库。运行 npx expo prebuild 可能无法按预期工作，因为项目现在处于不可预测的状态（可以将其想象为手动修改 node_modules 目录后运行 yarn）。

¥If you manually modify the android and ios directories, you must set up new libraries manually. Running npx expo prebuild may not work as expected because the project is now in an unpredictable state (think of this like running yarn after manually modifying your node_modules directory).

如果你想对原生项目文件（例如 AndroidManifest.xml 或 Info.plist）进行静态更改，并且仍然可以访问预构建，则创建 配置插件 以了解如何钩子预构建过程来进行这些更改。

¥If you want to make static changes to your native project files, such as AndroidManifest.xml or Info.plist, and still have access to prebuilding, then create a config plugin to see how you can hook into the prebuild process to make those changes.

恢复 npx expo run:[android|ios] 的更改

¥Revert changes from npx expo run:[android|ios]

假设你决定将应用回滚到完全托管状态（项目目录中没有 android 或 ios 目录）。在这种情况下，你可以在执行 npx expo run:[android|ios] 之前检查最近的提交，然后再次运行 npm install 以恢复 node_modules 目录的状态。

¥Suppose you have decided to roll your app back to being fully managed (no android or ios directories in your project directory). In that case, you can check out your most recent commit before executing npx expo run:[android|ios], then run npm install again to restore the state of your node_modules directory.

使用自定义原生代码开发应用

¥Develop apps with custom native code

在项目中自定义原生代码后，你可以将 expo-dev-client 库用于 创建开发版本，并保留在 Expo Go 中使用 JavaScript 或 TypeScript 的便利性。

¥Once you have customized the native code in your project, you can use the expo-dev-client library to create a development build and retain the convenience of working with JavaScript or TypeScript in Expo Go.

将具有自定义原生代码的应用发布到生产环境

¥Release apps with custom native code to production

当你准备好发布应用时，你可以在添加自定义原生代码之前按照构建应用时的方式进行 使用 EAS Build 进行构建。或者，你可以在本地存档并签名。毫不奇怪，我们推荐 EAS Build！

¥When you're ready to ship your app, you can build it with EAS Build the same as you were building it before adding custom native code. Alternatively, you can archive and sign it locally. Unsurprisingly, we recommend EAS Build!

创建可重用的原生模块

¥Create reusable native modules

除了向项目添加自定义原生代码之外，Expo 模块 API 还使开发者能够使用 Swift、Kotlin 和 TypeScript 为 Expo 和 React Native 项目构建可重用模块。这些模块通常发布到 npm。它们也可以作为单独的包包含在 monorepo 中。我们对 Expo SDK 中的大多数模块使用 Expo Modules API。

¥Apart from adding custom native code to a project, the Expo Modules API enables developers to build reusable modules for Expo and React Native projects using Swift, Kotlin, and TypeScript. These modules are often published to npm. They can also be included as separate packages within a monorepo. We use the Expo Modules API for most modules in the Expo SDK.

另一种选择是使用 React Native 的核心 Native 模块 API，除了 Objective-C 和 Java 之外，这可能还需要一些 C++ 知识。生态系统中的大多数 React Native 模块都是使用此 API 构建的，因为它始终是 React Native 的一部分。Expo Module API 是新的，旨在解决使用核心 API 的许多痛点。

¥Another option is to use React Native's Core Native Modules API, which may require some C++ knowledge in addition to Objective-C and Java. Most React Native modules in the ecosystem are built using this API because it is and always has been part of React Native. The Expo Module API is new and intends to solve many of the pain points of using the core API.