配置插件简介

Expo 配置插件简介。

在项目中使用 Continuous Native Generation (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 项目中修改在 预构建 过程中创建的原生项目。

🌐 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。在极少数情况下，如果用于与原生项目通信的方法是异步的，插件也可以是异步的，但性能不会很好。
• 插件应使用以下命名约定：with<Plugin Functionality>，例如，withFacebook
• 插件应该是同步的，并且它们的返回值应该是可序列化的，除了添加任何 mods 的情况
• 插件始终在应用配置评估阶段进行评估。
• （可选）可以将第二个参数传递给插件进行配置。
• Mods 仅在 npx expo prebuild 的 同步 阶段（预构建过程）进行评估，并在代码生成期间修改本地文件。因此，在配置插件中对应用配置所做的任何修改应位于 mod 之外，以确保它们在非预构建配置场景中也能执行。

开始使用

🌐 Get started