配置插件简介

Expo 配置插件简介。

在项目中使用 持续的原生生成 (CNG) 时，原生项目（Android 和 iOS 目录）的更改无需直接与原生项目文件交互即可实现。此外，你可以使用配置插件自动配置原生项目，而无需使用默认应用配置属性进行配置。

¥When using Continuous Native Generation (CNG) in a project, native project (android and ios directories) changes are implemented without directly interacting with the native project files. Instead, you can use a config plugin to automatically configure your native project beyond what can be configured using the default app config props.

什么是配置插件

¥What is a config plugin

配置插件是一个顶层自定义配置点，它未内置于 应用配置 中。使用配置插件，你可以在 CNG 项目中修改在 prebuild 过程中创建的原生项目。

¥A config plugin is a top-level custom configuration point that is not built into the app config. Using a config plugin, you can modify native projects created during the prebuild process in CNG projects.

配置插件在 应用配置 文件的 plugins 属性中引用，由一个或多个插件函数组成。这些插件函数用 JavaScript 编写，并在预构建过程中执行。

¥A config plugin is referenced in the plugins property of the app config file and is made up of one or more plugin functions. These plugin functions are written in JavaScript and are executed during the prebuild process.

词汇表

¥Glossary

一个典型的配置插件由一个或多个协同工作的插件函数组成。下图展示了配置插件各个部分之间的交互方式：

¥A typical config plugin is made up of one or more plugin functions that work together. The following diagram shows how the different parts of a config plugin interact with each other:

在以下指南中，我们将使用上图高亮下文解释的特定术语：

¥In the following guides, we will use the above diagram to highlight specific terminology explained below:

插件

¥Plugin

顶层配置插件，在你的应用配置的 plugins 数组中引用。这是插件的入口点。通常，它被命名为 with<Plugin Name>。例如，withMyPlugin。它由一个或多个 插件功能 组成。

¥The top-level config plugin which is referenced in your app config's plugins array. This is the entry point for your plugin. Conventionally, it is named with<Plugin Name>. For example, withMyPlugin. It is made of one or more plugin functions.

插件功能

¥Plugin function

配置插件中的一个或多个函数称为插件函数。它们封装了执行平台特定修改的底层逻辑。从技术上讲，插件函数看起来与顶层插件本身的函数一样，并且可以独立用作插件。将插件拆分成更小的函数通常有助于测试和调试。

¥One or more functions inside a config plugin that are called plugin functions. They wrap the underlying logic of performing platform-specific modifications. Technically, plugin functions look just like the function for the top-level plugin itself, and could be used as a plugin independently. Breaking plugins into smaller functions is often helpful for testing and debugging.

Mod 插件功能

¥Mod plugin function

来自 expo/config-plugins 库的封装函数，提供使用 mods 修改原生文件的安全方法。作为开发者，你将在配置插件中使用这些功能，而不是在底层 mods 中。

¥Wrapper functions from expo/config-plugins library that provide a safe way to modify native files using mods. As a developer, you will use these functions in your config plugin instead of underlying mods.

Mod

在预构建期间直接修改原生项目文件的底层平台特定修饰符（例如 mods.android.manifest 和 mods.ios.infoplist）。

¥The underlying platform-specific modifiers (like mods.android.manifest and mods.ios.infoplist) that directly modify native project files during prebuild.

为什么使用配置插件

¥Why use a config plugin

配置插件可以向你的项目添加默认情况下不包含的原生配置。它们可用于生成应用图标、设置应用名称、配置 AndroidManifest.xml 和 Info.plist 等等。

¥Config plugins can add native configuration to your project that isn't included by default. They can be used to generate app icons, set the app name, configure AndroidManifest.xml and Info.plist, and so on.

在 CNG 项目中，最好避免手动修改这些原生项目，因为你无法安全地重新生成它们，否则可能会覆盖手动修改。配置插件允许你以可预测的方式修改这些原生项目，方法是将原生项目的更改合并到配置文件中，并在运行 npx expo prebuild（在 CI/CD 过程中手动或自动）时应用这些更改。例如，当你在应用配置中更改应用名称并运行 npx expo prebuild 时，该名称将在你的原生项目中自动更改，无需手动更新 AndroidManifest.xml 和 Info.plist 文件。

¥In CNG projects, it is best to avoid modifying these native projects manually, because you cannot regenerate them safely without potentially overwriting manual modifications. Config plugins allow you to modify these native projects in a predictable way by consolidating your native project changes into a configuration file and applying them when you run npx expo prebuild (either manually or automatically during a CI/CD process). For example, when you change the name of your app in app config and run npx expo prebuild, the name will change in your native projects automatically without the need to manually update AndroidManifest.xml and Info.plist files.

配置插件的特点

¥Characteristics of a config plugin

配置插件具有以下特点：

¥Config plugins have the following characteristics:

• 插件是同步函数，接受 ExpoConfig 并返回修改后的 ExpoConfig。在极少数情况下，如果与原生项目通信的可用方法是异步的，则插件也可以是异步的，但性能不佳。

  ¥Plugins are synchronous functions that accept an ExpoConfig and return a modified ExpoConfig. In rare cases, plugins can also be asynchronous if available methods to communicate with native projects are asynchronous, but they won't be performant.

• 插件应使用以下约定命名：with<Plugin Functionality>，例如 withFacebook

  ¥Plugins should be named using the following convention: with<Plugin Functionality>, for example, withFacebook

• 插件应同步运行，并且其返回值应可序列化，但添加任何 mods 除外。

  ¥Plugins should be synchronous and their return value should be serializable, except for adding any mods

• 插件始终在应用配置评估阶段进行评估。

  ¥Plugins are always evaluated during the app config evaluation phase.

• （可选）可以将第二个参数传递给插件进行配置。

  ¥Optionally, a second argument can be passed to the plugin to configure it

• 模块仅在 npx expo prebuild（预构建过程）的同步阶段进行评估，并在代码生成期间修改原生文件。因此，在配置插件中对应用配置所做的任何修改都应在模块之外进行，以确保它们在非预构建配置场景中执行。

  ¥Mods are only evaluated during the syncing phase of npx expo prebuild (prebuild process) and modify native files during code generation. Because of that, any modifications made to app config in a config plugin should be outside of a mod to ensure that they are executed in non-prebuild configuration scenarios.

开始使用

¥Get started