首页指南EAS参考教程

持续的原生生成 (CNG)

了解如何使用持续原生生成 (CNG) 和预构建来管理你的原生项目。

单个原生项目本身的维护、扩展和更新都很复杂。在跨平台应用中，你有多个原生项目，你必须维护这些项目并保持最新的操作系统版本，以避免在任何第三方依赖中落后太多。

¥A single native project on its own is complicated to maintain, scale, and update. In a cross-platform app, you have multiple native projects that you must maintain and keep up to date with the latest operating system releases to avoid falling too far behind in any third-party dependencies.

随着你的原生项目的增长，来自第三方依赖的复杂性也会增加，从而使升级变得复杂并减缓开发者的开发速度。这不鼓励添加高级原生功能，并导致应用功能减弱。在跨平台应用中，这种复杂性在每个平台上都会成倍增加。

¥As your native project grows, the complexity from third-party dependencies increases, complicating upgrades and slowing down developer momentum. This discourages adding advanced native functionality and leads to less powerful apps. In cross-platform apps, this complexity is multiplied across each platform.

为了解决这个问题，我们引入了持续原生生成的概念。不是一次性创建原生项目并在代码库的整个生命周期内维护对这些原生项目的自定义，而是仅在需要时（例如调试或构建时）生成短暂的原生项目。这些项目是从标准模板加上配置或定义如何自定义模板的自定义代码生成的。结果是一个原生项目，可以编译成原生应用，并根据开发者的需要进行任何自定义。但是，开发者只负责维护其自定义的定义，而不是所有原生项目代码。

¥To address this, we've introduced the concept of Continuous Native Generation. Instead of creating native projects a single time and maintaining customizations to those native projects for the lifetime of the codebase, short-lived native projects are generated only when needed, such as when debugging or building. These projects are generated from a standard template plus configuration or custom code that defines how the template should be customized. The result is a native project that can be compiled into a native app with any customizations desired by the developer. However, the developer is responsible for only maintaining the definition of their customizations, rather than all of the native project code.

React Native 应用中的 CNG

¥CNG in React Native apps

React Native 应用可以使用 预建 使用 CNG 来自动升级、安装或卸载库、应用白标自定义、跨多个应用共享配置、减少 孤立代码 等等。

¥React Native apps can use CNG by using Prebuild to automate upgrades, install or uninstall libraries, apply white label customizations, share configuration across multiple apps, reduce orphaned code, and more.

Expo 作为一个框架，通过结合以下工具来启用 CNG：

¥Expo as a framework enables CNG by combining the following tools:

  1. 应用配置 文件。

    ¥The app config file.

  2. 传递给 npx expo prebuild 命令的参数。

    ¥Arguments passed to the npx expo prebuild command.

  3. 项目中安装的 expo 版本以及相应的 预构建模板。

    ¥Version of expo that's installed in the project and corresponding prebuild template.

  4. 自动链接，用于链接 package.json 中找到的 原生模块。

    ¥Autolinking, for linking native modules found in the package.json.

  5. 原生订阅者，用于减少入口点文件中的原生代码副作用，例如 MainApplication 或 AppDelegate。

    ¥Native subscribers, for reducing native code side-effects in entry point files, such as MainApplication or AppDelegate.

  6. 用于代码签名附加目标和权利的 EAS 凭证。

    ¥EAS Credentials for code signing additional targets and entitlements.

最终结果是一个工作流程，开发者可以使用应用配置表达任何原生应用并通过运行 npx expo prebuild 连续生成该项目。

¥The end result is a workflow where a developer can express any native application with the app config and generate that project continuously — by running npx expo prebuild.

用法

¥Usage

可以通过运行以下命令来使用预构建：

¥Prebuild can be used by running:

Terminal
- npx expo prebuild

这将创建用于运行 React 代码的 android 和 ios 目录。如果你手动修改生成的目录，那么你下次运行 npx expo prebuild --clean 时可能会丢失所做的更改。相反，使用 配置插件 ，它们是在预构建期间对原生项目执行修改的函数。

¥This creates the android and ios directories for running your React code. If you modify the generated directories manually then you risk losing your changes the next time you run npx expo prebuild --clean. Instead, use config plugins , which are functions that perform modifications on native projects during prebuild.

我们强烈建议你出于 常见问题 部分中列出的原因使用 Prebuild，但系统是 完全可选，你可以随时停止使用它。

¥We highly recommend using Prebuild for the reasons listed in the common questions section, but the system is fully optional, and you can stop using it at any time.

与 EAS 构建一起使用

¥Usage with EAS Build

如果你的项目不包含 android 和 ios 目录，EAS Build 将在编译前运行 Prebuild 生成这些原生目录。这是使用 npx create-expo-app 创建的任何项目的默认行为。

¥If your project does not contain android and ios directories, EAS Build will run Prebuild to generate these native directories before compilation. This is the default behavior for any project created using npx create-expo-app.

对于具有 android 和 ios 目录的项目，EAS Build 将不会运行 Prebuild，以避免覆盖你对原生目录所做的任何更改。

¥For a project that has android and ios directories, EAS Build will not run Prebuild to avoid overwriting any changes you've made to the native directories.

如果你通过 本地编译（运行 npx expo prebuild、或 npx expo run:android 或 npx expo run:ios）对应用进行故障排除，你仍然可以使用 Prebuild 和 EAS Build 在构建过程中生成新的原生目录。在这种情况下，将 android 和 ios 目录添加到 .gitignore 或 .easignore 文件中：

¥If you troubleshoot your app by compiling it locally (running npx expo prebuild, or npx expo run:android or npx expo run:ios), you can still use Prebuild with EAS Build to generate fresh native directories during the build process. In this scenario, add the android and ios directories to .gitignore or .easignore files:

.gitignore
+ /android
+ /ios

与 Expo CLI 运行命令一起使用

¥Usage with Expo CLI run commands

你可以通过运行以下命令在本地执行原生构建：

¥You can perform a native build locally by running:

Terminal
# Build your native Android project
- npx expo run:android

# Build your native iOS project
- npx expo run:ios

如果原生目录不存在，npx expo prebuild 将针对特定平台运行一次。在随后使用这些 run 命令时，请手动运行 npx expo prebuild --clean 以确保原生代码与你的本地配置最新同步。

¥If native directories are absent, npx expo prebuild will run once for the specific platform. On subsequent uses of these run commands, manually run npx expo prebuild --clean to ensure the native code is freshly synchronized with your local configuration.

平台支持

¥Platform support

Prebuild 目前支持 Android 和 iOS。不需要 Web 支持，因为没有为 Web 和它在 Web 浏览器中运行的 Web 应用生成的原生项目。使用 --platform 选项为各个平台运行预构建：

¥Prebuild currently supports Android and iOS. Web support is not required because there is no native project to generate for the web and the web app it runs in a web browser. Use the --platform option to run prebuild for individual platforms:

Terminal
- npx expo prebuild --platform ios

依赖

¥Dependencies

Prebuild 首先从与每个 Expo SDK 版本相对应的模板初始化新的原生项目。这也与特定的 React 和 React Native 版本一致。如果项目的 React 和 React Native 版本与 模板的 package.json 的 dependencies 字段中指定的预期版本不同，则在运行 npx expo prebuild 时你将看到警告。

¥Prebuild begins by initializing new native projects from a template corresponding to each Expo SDK version. This also aligns with specific React and React Native versions. You will see a warning when running npx expo prebuild when your project's React and React Native versions differ from the expected versions from specified in the dependencies field of the template's package.json if they differ.

你可以使用 --skip-dependency-update 选项跳过更改 npm 包版本：

¥You can skip changing npm package versions with the --skip-dependency-update option:

Terminal
- npx expo prebuild --skip-dependency-update react-native,react

包管理器

¥Package managers

当 dependencies 发生更改时，Prebuild 将使用项目当前使用的包管理器重新安装库（这是从锁定文件中推断出来的）。你可以通过提供以下之一来强制使用特定的包管理器：--npm、--yarn、--pnpm。

¥When the dependencies are changed, Prebuild will reinstall libraries using the package manager that is currently used in the project (this is inferred from the lockfile). You can force a specific package manager by providing one of: --npm, --yarn, --pnpm.

通过传递 --no-install 命令可以跳过所有安装，这对于快速测试生成很有用。

¥All installations can be skipped by passing the --no-install command, which is useful for testing generation quickly.

清理

¥Clean

--clean 选项在生成之前删除任何现有的原生目录。在没有 --clean 选项的情况下重新运行 npx expo prebuild 将在现有文件之上分层更改，这样速度更快，但在某些情况下可能不会产生相同的结果。

¥The --clean option deletes any existing native directories before generating. Re-running npx expo prebuild without the --clean option will layer changes on top of the existing files, which is faster, but may not produce the same results in some cases.

例如，一些配置插件不是幂等的。当项目利用多个 "危险修饰语" 将正则表达式更改添加到应用代码时，可能会导致意外行为。这就是为什么使用 --clean 选项是使用预构建命令的最安全方式，并且通常在大多数情况下都推荐这样做。

¥For example, some config plugins aren't idempotent. When a project utilizes multiple "dangerous modifiers" to add regex changes to an app's code, it can lead to unexpected behavior. This is why using the --clean option is the safest way to use the prebuild command and is generally recommended in most cases.

使用 --clean 选项

¥Using --clean option

使用 --clean 选项时，如果你对 git 代码存储库有任何未提交的更改，你将收到警告，因为此选项将删除并重新创建所有原生项目文件。该提示是可选的，在 CI 中遇到时会跳过。你可以通过启用环境变量 EXPO_NO_GIT_STATUS=1 来禁用此检查。

¥When using the --clean option, you'll be warned if you have any uncommitted changes to your git code repository, as this option will delete and recreate all of your native project files. This prompt is optional and will be skipped when encountered in CI. You can disable this check by enabling the environment variable EXPO_NO_GIT_STATUS=1.

在某些情况下，开发者可能希望经常在工作流程之间进行交换。例如，你可能希望在 Android Studio 和 Xcode 中原生构建自定义功能，然后将该功能移至本地配置插件中。

¥There are cases where developers may want to swap between workflows often. For example, you may want to build custom functionality natively in Android Studio and Xcode, and then move that functionality into local config plugins.

模板

¥Templates

你可以自定义 配置插件 生成原生目录的方式。许多配置插件已经存在，可以进行大量修改，社区库也经常提供自己的插件。你可以 查看一些流行插件的列表 了解更多信息。

¥You can customize how the native directories are generated by config plugins. Many config plugins already exist for lots of modifications, and community libraries often ship their own as well. You can see a list of some popular plugins for more information.

Prebuild 从模板文件开始，然后使用配置插件进行修改。模板文件基于 Expo SDK 版本，来自 npm 包 expo-template-bare-minimum。你可以通过将 --template /path/to/template.tgz 传递给 npx expo prebuild 命令来更改使用的模板。通常不建议这样做，因为 @expo/prebuild-config 中的基本修饰符对模板文件做出了一些未记录的假设，因此维护自定义模板可能很棘手。

¥Prebuild starts from template files, which are then modified with config plugins. The template files are based on the Expo SDK version and come from the npm package expo-template-bare-minimum. You can change the template used by passing --template /path/to/template.tgz to the npx expo prebuild command. This is not generally recommended because the base modifiers in @expo/prebuild-config make some undocumented assumptions about the template files, so it may be tricky to maintain your custom template.

注意：在所有包都是从私有注册表下载并且 npm 公共注册表访问被阻止的网络环境中，必须将本地可用的模板传递给预构建命令。了解有关使用默认模板的本地版本的详细信息。

¥Note: In network environments where all packages are downloaded from a private registry and npm public registry access is blocked, a locally-available template must be passed to the prebuild command. Learn more about using a local version of the default template.

副作用

¥Side effects

除了生成 android 和 ios 目录之外，npx expo prebuild 还执行一些副作用。消除这些副作用的工作正在进行中 - 理想情况下，运行 npx expo prebuild 将生成 Android 和 iOS 项目，并且项目的其余部分保持不变。

¥npx expo prebuild performs several side effects outside of generating the android and ios directories. Work is in progress to eliminate these side effects — ideally, running npx expo prebuild would generate the Android and iOS projects and leave the rest of the project untouched.

除了生成原生目录外，prebuild 还进行了以下修改：

¥In addition to generating the native directories, prebuild also makes the following modifications:

  • 修改 package.json 中的 scripts 字段，将 expo start --android 和 expo start --ios 替换为 expo run:android 和 expo run:ios

    ¥Modifies the scripts field in the package.json to replace expo start --android and expo start --ios with expo run:android and expo run:ios

  • 修改 package.json 中的 dependencies 字段

    ¥Modifies the dependencies field in the package.json

对 scripts 字段的方便更改是改变开发者在预构建之前/之后处理应用的方式的唯一副作用。所有其他更改都可以保留并提交给 git，以最大限度地减少运行预构建时的差异。

¥The convenience change to the scripts field is the only side effect that alters how a developer works on their app before/after prebuild. All other changes can be left in place and committed to git to minimize the diff when running prebuild.

可选

¥Optionality

Prebuild 是可选的，可与所有 Expo 工具和服务无缝协作。对于现有的 React Native 项目，其中原生项目是手动管理的，请勿使用 npx expo prebuild，因为这可能会覆盖任何手动自定义。开发者可以在采用其他 Expo 工具和工作流程的同时继续制作 (直接更改其原生项目)。稍后，他们可以将手动自定义移动到应用配置和/或配置插件，然后采用 CNG。

¥Prebuild is optional and works seamlessly with all Expo tools and services. For existing React Native projects, where the native projects are managed manually, do not use npx expo prebuild, as that may overwrite any manual customizations. Developers can continue to make (direct changes to their native projects) while adopting other Expo tools and workflows. Later on, they can move their manual customizations to app config and/or config plugins, and then adopt CNG.

Expo 提供的所有内容，包括 EAS、Expo CLI 和 Expo SDK 中的库，都是为完全支持裸 React Native 项目而构建的，因为这是使用 npx expo prebuild 支持项目的最低要求。唯一的例外是 Expo 应用，它只能在包含 Expo Go 运行时中不存在的原生代码的 JavaScript 回退时加载任意 React Native 项目。

¥Everything offered by Expo including EAS, Expo CLI, and the libraries in the Expo SDK are built to fully support bare React Native projects as this is a minimum requirement for supporting projects using npx expo prebuild. The only exception is the Expo Go app, which can load arbitrary React Native projects only if they include JavaScript fallbacks for native code absent in the Expo Go runtime.

常见问题

¥Common questions

CNG

How does CNG helps with project upgrades?

不使用 Continuous Native Generation 的 React Native 开发者报告说，根据 React Native 调查 (2022)，将他们的应用升级到最新版本的 React Native 是该库的第一个弱点。

¥React Native developers who don't use Continuous Native Generation have reported that upgrading their apps to the latest version of React Native is the number one weakness of the library as per React Native Survey (2022).

使用 CNG 时，升级过程仅涉及升级 npm 依赖、应用配置和重新运行 npx expo prebuild --clean。

¥When using CNG, the upgrade process simply involves upgrading the npm dependencies, app config, and re-running npx expo prebuild --clean.

How a React Native library author can adopt CNG?

React Native 库作者可以通过多种方式采用 CNG。这取决于其库的复杂性。以下是一些场景：

¥React Native library authors can adopt CNG in several ways. It depends on the complexity of their libraries. Here are a few scenarios:

  • 无原生代码或配置副作用：没有原生代码或配置副作用的库（例如 react-native-blurhash）可以与 npx expo prebuild 无缝集成。它们可以依赖 Node Module Resolution，而无需任何额外配置。

    ¥No native code or configuration side-effects: Libraries without native code or configuration side-effects, such as react-native-blurhash, can seamlessly integrate with npx expo prebuild. They can rely on Node Module Resolution without requiring any additional configuration.

  • 安装后无需额外设置的原生代码：带有原生代码的库通常可以安装并自动链接到 Expo 自动链接，它在构建原生应用之前运行。

    ¥Native code with no additional setup after install: Libraries with native code can often be installed and linked automatically with Expo Autolinking, which runs before the native app is built.

  • 其他配置副作用和设置：需要额外配置副作用的库可以通过为其库创建 Expo 配置插件 来采用 CNG。这种方法使库作者能够自动添加值，例如将权限消息添加到 Info.plist，或在 Xcode 项目中注入目标。

    ¥Additional configuration side-effects and setup: Libraries that require additional configuration side-effects can adopt CNG by creating Expo config plugins for their libraries. This approach enables library authors to automate adding values such as permission messages to the Info.plist, or injecting targets in the Xcode project.

  • 依赖于原生运行时钩子的库：依赖于特定原生运行时钩子的库（例如通过 AppDelegate、MainActivity、MainApplication 等拦截初始启动 URL）可以在 Expo Modules API 中使用 生命周期监听器。这些生命周期监听器允许通过 Expo Autolinking 应用这些运行时钩子，而不是通过修改这些标准原生项目文件，从而无需配置插件。

    ¥Libraries Dependent on Native Runtime Hooks: Libraries that depend on specific native runtime hooks, such as intercepting the initial launch URL via the AppDelegate, MainActivity, MainApplication, and so on, can utilize Lifecycle listeners in the Expo Modules API. These lifecycle listeners allow these runtime hooks to be applied via Expo Autolinking instead of by modifying these standard native project files, eliminating the need for a config plugin.

许多复杂的库和服务已经通过 Expo Prebuild 支持 CNG，例如 MapBox、OneSignal、条纹 和 React Native Firebase。

¥Many complex libraries and services already support CNG via Expo Prebuild such as, MapBox, OneSignal, Stripe, and React Native Firebase.

库作者采用 CNG 不是使用 npx expo prebuild 的先决条件。如果库作者尚未采用 CNG，开发者仍可以通过创建本地 配置插件 来修改原生生成管道，从而使用 npx expo prebuild。这种灵活性使 CNG 可供 React Native 社区内的所有开发者使用和受益。

¥Adopting CNG by library authors is not a preqrequisite for using npx expo prebuild. If a library author has not adopted CNG, developers can still use npx expo prebuild by creating local Config Plugins to modify the native generation pipeline. This flexibility makes CNG accessible and beneficial to all developers within the React Native community.

Is CNG limited to React Native projects?

不，CNG 是一种多功能模式，可以应用于任何原生项目。虽然 Expo Prebuild 是专门为 React Native 项目实现 CNG 的工具，但概念本身并不限于此框架。

¥No, CNG is a versatile pattern that can be applied to any native project. While Expo Prebuild is a tool that implements CNG specifically for React Native projects, the concept itself is not limited to this framework.

How does community uses CNG?

以下是一些社区示例，将难以实现的原生功能转换为简单的配置文件，这些文件使开发者能够构建更强大的应用，而不会影响迭代速度：

¥Here are a few community examples of difficult native features converted into simple configuration files, which have allowed developers to build more powerful apps without compromising on iteration speed:

  • iOS Safari 扩展：在这里，创建 iOS 版 Safari 扩展的过程（众所周知，这是一个难以实现的功能）被简化为几行 JSON。

    ¥iOS Safari Extensions: Here, the process of creating a Safari Extension for iOS, which is a notoriously difficult feature to implement, is reduced to a few of lines of JSON.

  • iMessage 贴纸应用：此 Expo 配置插件可以从 JSON 对象生成整个 iMessage Sticker App。

    ¥iMessage Sticker App: This Expo config plugin can generate an entire iMessage Sticker App from a JSON object.

  • 跨平台端到端测试：配置原生应用以在一行中支持使用 Detox 进行 E2E 测试。

    ¥Cross-platform end-to-end testing: Configure native apps to support E2E testing with Detox in a single-line.

  • 整个 Firebase 套件：在这里，你可以看到整个原生 Firebase 套件从跨多个 IDE 的多步骤原生配置过程到基本的 JSON 配置。

    ¥The entire Firebase suite: Here you can see the entire native Firebase suite going from a multi-step native configuration process across multiple IDEs, down to basic JSON configuration.

  • 跨平台主屏幕小部件：此 Expo 配置插件可以为 Android 和 iOS 生成主屏幕小部件。

    ¥Cross-platform home screen widgets: This Expo config plugin can generate a home screen widget for Android and iOS.

  • 通知扩展和代码签名：此 Expo 配置插件在 iOS 上生成通知扩展目标，并增强 EAS 凭据服务以保持零配置代码签名正常工作。

    ¥Notification extension and code signing: This Expo config plugin generates a notification extension target on iOS and it augments the EAS credentials service to keep zero-config code signing working.

  • 苹果应用剪辑：此 Expo 配置插件采用从多步骤过程生成 Apple App Clip 的过程，涵盖多个目标，并将其缩减为单行 ["react-native-app-clip", { "name": "My App Clip" }]。

    ¥Apple App Clips: This Expo config plugin takes the process of generating an Apple App Clip from a multi-step process, ranging across multiple targets, and reduces it to a single line ["react-native-app-clip", { "name": "My App Clip" }].

在任何时候，都可以轻松添加和删除这些功能，而不会产生任何副作用。CNG 允许开发者尝试复杂的功能并快速迭代它们，而不必担心长期维护成本或项目中潜在的孤立代码。

¥At any point, these features can be easily added and removed, without any side effects. CNG allows developers to experiment with complex features and iterate on them quickly without worrying about the long-term maintenance costs or potential orphaned code in their project.

Can CNG be used for operating systems other than Android and iOS?

绝对地！CNG 是一个抽象概念，可以应用于任何操作系统。虽然 Expo Prebuild 正式为 Android 和 iOS 实现了 CNG，但它还为开发者提供了抽象平台支持，以便为其他平台创建实现。

¥Absolutely! CNG is an abstract concept that can be applied to any operating system. Although Expo Prebuild officially implements CNG for Android and iOS, it also provides abstract platform support for developers to create implementations for additional platforms.

Is using Expo a requirement for CNG?

一点也不。CNG 是一种开放的模式，任何社区都可以采用。我们抽象地定义了该模式，以帮助其他社区了解如何在自己的项目中采用 CNG。

¥Not at all. CNG is an open pattern that can be adopted by any community. We've defined the pattern abstractly to help other communities understand how they can adopt CNG for their own projects.

How does CNG compare to web development patterns such as Static Site Generation (SSG)?

CNG 与 SSG 的相似之处在于，它根据一组输入生成一个项目。但是，CNG 的输出与 SSG 不同。它生成原生运行时代码而不是静态网站代码。这意味着原生项目是按需生成的，一旦原生项目编译成原生应用，生成的源代码和配置就会被丢弃。

¥CNG shares similarities with SSG in that it generates a project from a set of inputs. However, CNG differs from SSG in its output. It generates native runtime code instead of static website code. This means the native project is generated on-demand, and the generated source code and configuration are discarded once the native project is compiled into a native app.

Is it possible to use CNG with an existing brownfield project?

CNG 旨在持续管理原生项目的整个状态。因此，它不适用于现有的棕地项目。但是，你可以使用 CNG 生成新的原生项目，然后将其集成到现有的棕地项目中。

¥CNG is designed to manage the entire state of a native project continuously. As a result, it's not intended for use with existing brownfield projects. However, you can use CNG to generate a new native project, which can then be integrated into an existing brownfield project.

预建

¥Prebuild

Expo Prebuild 简化了 CNG 处理。以下是 Prebuild 解决的 React Native 开发周期中的一些问题：

¥Expo Prebuild streamlines CNG processing. Here are some issues in the React Native development cycle that are addressed by Prebuild:

How can Prebuild help with sensible project upgrades?

构建原生代码需要熟悉平台的工具，因此学习曲线很陡峭。由于多个平台，跨平台开发中的这一挑战更加严峻。如果你必须在特定于平台的原生代码中实现许多功能，跨平台工具将无济于事。

¥Building native code requires familiarity with the platform's tooling, creating a steep learning curve. This challenge intensifies in cross-platform development due to multiple platforms. Cross-platform tooling doesn't help if you must implement many features in platform-specific native code.

在引导原生应用时，可能会出现你可能不理解的初始代码和配置。但你不负责维护它。最终，你需要了解此代码才能安全地升级你的应用。这一挑战常常导致开发者错误地升级或启动新应用，复制现有的源代码。

¥When bootstrapping a native app, there's initial code and configuration that you may not understand. Yet you are not responsible for maintaining it. Eventually, you'll need to understand this code to upgrade your app safely. This challenge often leads developers to upgrade incorrectly or start a new app, copying existing source code.

使用 Prebuild，升级更接近于升级纯 JavaScript 应用。在你的 package.json 中增加版本，重新生成原生项目，然后你就可以继续开发了。

¥With Prebuild, upgrading is much closer to upgrading a pure JavaScript application. Bump the versions in your package.json, regenerate the native project, and you should be ready to continue development.

How does Prebuild simplify cross-platform configuration?

应用图标、名称、启动画面等跨平台配置必须在原生代码中手动实现。这些实现通常在每个平台上都有很大不同。

¥Cross-platform configurations such as the app icon, name, splash screen, and so on must be implemented manually in native code. These implementations are often quite different for each platform.

使用 Prebuild，跨平台配置是在配置插件级别处理的，开发者只需设置一个值（如 "icon": "./icon.png"）即可处理所有图标生成。

¥With Prebuild cross-platform configurations are handled at the config plugin level, and the developer only needs to set a single value like "icon": "./icon.png" to have all icon generation taken care of.

How can I manage dependency side-effects with Prebuild?

许多复杂的原生包需要除安装和 autolinking 之外的其他设置。例如，相机库需要添加权限设置 AndroidManifest.xml（适用于 Android）和 Info.plist（适用于 iOS）。这个额外的设置可以被认为是包的配置副作用。将所需的副作用代码粘贴到项目的原生文件中可能会导致严重的原生编译错误，而且它也是你现在拥有和维护的代码。

¥Many complex native packages require additional setup beyond installing and autolinking. For example, a camera library requires permission settings to be added AndroidManifest.xml for Android and Info.plist for iOS. This additional setup can be considered a configuration side effect of a package. Pasting the required side effect code into your project's native files can lead to difficult native compilation errors, and it's also code that you now own and maintain.

通过预构建库，作者比任何人都更了解如何配置他们的库，他们可以创建一个名为 配置插件 的可测试和版本化脚本，以自动为其库添加所需的配置副作用。这意味着库副作用可以更具表现力、更强大、更稳定。对于原生代码副作用，我们还提供了默认 预构建模板 中标配的 Android 生命周期监听器 和 AppDelegate 订阅者。

¥With Prebuild library authors, who know how to configure their library better than anyone, can create a testable and versioned script called a config plugin, to automate adding the required configuration side effects for their library. This means library side effects can be more expressive, powerful, and stable. For native code side effects, we also provide Android Lifecycle Listeners and AppDelegate Subscribers which come standard in the default prebuild template.

How does Prebuild help with orphaned code?

当你卸载包时，你必须确定你已删除使该包工作所需的所有副作用。如果你遗漏了任何内容，就会导致你无法追溯到任何特定包的孤立代码，这些代码会不断累积并使你的项目更难以理解和维护。

¥When you uninstall a package, you have to be certain you removed all of the side effects required to make that package work. If you miss anything, it leads to orphaned code that you cannot trace back to any particular package, this code builds up and makes your project harder to understand and maintain.

使用 Prebuild 的唯一副作用是项目的 Expo 配置 (app.json) 中的 配置插件，当卸载相应的节点模块时，它会抛出错误，这意味着孤立的配置会减少很多。

¥With Prebuild the only side effect is the config plugin in a project's Expo config (app.json), which will throw an error when the corresponding node module has been uninstalled, meaning a lot less orphaned configuration.

When Prebuild might not be the right fit for a project

以下是 Expo Prebuild 可能不适合特定项目的一些原因：

¥Here are some reasons Expo Prebuild might not be the right fit for a particular project:

平台兼容性

¥Platform compatibility

Prebuild 只能用于 Expo SDK 支持的原生平台。暂时指的是 Android 和 iOS。Web 除外，它不需要 npx expo prebuild，因为它使用浏览器而不是自定义原生运行时。

¥Prebuild can only be used for native platforms that are supported by the Expo SDK. This means Android and iOS for the time being. Except for web, which doesn't require npx expo prebuild since it uses the browser instead of a custom native runtime.

直接进行更改比模块化和自动化更快

¥Making changes directly is quicker than modularizing and automating

所有原生更改都必须添加原生模块（使用 React Native 的内置原生模块 API 或 Expo Modules API）和配置插件。这意味着，如果你想快速将原生文件添加到项目中进行实验，那么你最好运行预构建并手动添加文件，然后使用 monorepo.1 重新进入系统。我们计划通过向 Expo 自动链接 添加功能来加快此过程，该功能可在原生目录之外查找原生项目文件并在构建之前链接它们。

¥All native changes must be added with native modules (using React Native's built-in Native Module APIs or the Expo Modules API) and config plugins. This means if you want to quickly add a native file to your project to experiment, then you may be better off running prebuild and adding the file manually, then working your way back into the system with a monorepo. We plan to speed this process up by adding functionality to Expo Autolinking that finds native project files outside of the native directories and links them before building.

如果你想修改配置，例如 gradle.properties 文件，你必须编写一个插件（example）。这可以通过帮助插件库轻松实现自动化，但是，如果你需要经常这样做，速度会慢一些。

¥If you want to modify the configuration, such as the gradle.properties file, you'll have to write a plugin (example). This can be easily automated with helper plugin libraries, however, it is a bit slower if you need to do it often.

社区中的配置插件支持

¥Config plugin support in the community

并非所有软件包都支持 Expo Prebuild。如果你发现某个库在安装后需要额外设置并且还没有配置插件，我们建议你打开拉取请求或问题，以便维护者了解该功能请求。

¥Not all packages support Expo Prebuild yet. If you find a library that requires extra setup after installation and doesn't yet have a config plugin, we recommend opening a pull request or an issue so that the maintainer is aware of the feature request.

许多软件包（例如 react-native-blurhash）除了 autolinking 处理的内容之外不需要任何额外的原生配置，因此不需要配置插件。

¥Many packages, such as react-native-blurhash, don't require any additional native configuration beyond what is handled by autolinking and so no config plugin is required.

其他软件包，例如 react-native-ble-plx，确实需要额外的设置，因此需要一个配置插件与 npx expo prebuild 一起使用（在这种情况下，有一个名为 @config-plugins/react-native-ble-plx 的外部插件）。

¥Other packages, such as react-native-ble-plx, do require additional setup and therefore require a config plugin to be used with npx expo prebuild (in this case there's an external plugin called @config-plugins/react-native-ble-plx).

另外，我们还有 树外配置插件 的存储库，它为尚未采用该系统的流行软件包提供插件。可以将其想象为 TypeScript 的 DefinitelyTyped。我们更喜欢软件包提供自己的配置插件，但如果他们尚未采用该系统，社区可以使用存储库中列出的软件包。

¥Alternatively, we also have a repo for out-of-tree config plugins which provides plugins for popular packages that haven't adopted the system yet. Think of this like DefinitelyTyped for TypeScript. We prefer packages ship their own config plugin, but if they haven't adopted the system yet, the community can use the packages listed in the repo.