This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo 配置插件简介。

在项目中使用 Continuous Native Generation (CNG) 时，本机项目（android 和 ios 目录）的更改是在不直接与本机项目文件交互的情况下实现的。相反，你可以使用 config plugin，在默认 app config props 所能配置的范围之外，自动配置你的本机项目。

什么是配置插件

配置插件是一个顶层的自定义配置入口点，它并不是内置在 应用配置 中的。使用配置插件，你可以在 CNG 项目的 预构建 过程中修改生成的原生项目。

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

术语表

一个典型的配置插件由一个或多个协同工作的插件函数组成。下图展示了配置插件的不同部分如何相互作用：

在下面的指南中，我们将使用上图来突出显示下面解释的特定术语：

插件

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

插件函数

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

Mod 插件函数

来自 expo/config-plugins 库的包装函数，它们提供了一种安全的方式，使用 mods 来修改本机文件。作为开发者，你会在配置插件中使用这些函数，而不是直接使用底层的 mods。

Mod

底层的平台特定修改器（例如 mods.android.manifest 和 mods.ios.infoplist），它们会在预构建期间直接修改本机项目文件。

为什么使用配置插件

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

在 CNG 项目中，最好避免手动修改这些本机项目，因为你无法在不覆盖手动修改的情况下安全地重新生成它们。配置插件允许你以 可预测的方式 修改这些本机项目：将你的本机项目更改整合到一个配置文件中，并在你运行 npx expo prebuild 时应用它们（无论是手动运行还是在 CI/CD 流程中自动运行）。例如，当你在应用配置中更改应用名称并运行 npx expo prebuild 时，名称会自动更新到你的本机项目中，而无需手动更新 AndroidManifest.xml 和 Info.plist 文件。

配置插件的特性

配置插件具有以下特性：

• 插件是同步函数，接受一个 ExpoConfig 并返回修改后的 ExpoConfig。在极少数情况下，如果与原生项目通信的方法是异步的，插件也可以是异步的，但其性能会较差。
• 插件应遵循以下命名约定：with<Plugin Functionality>，例如 withFacebook
• 插件应当是同步的，并且其返回值应当是可序列化的，但添加任何 mods 除外
• 插件始终在应用配置评估阶段执行。
• 可以选择向插件传递第二个参数来对其进行配置
• Mods 仅在 npx expo prebuild 的同步阶段（预构建过程）执行，并在代码生成期间修改原生文件。因此，对应用配置所做的任何修改都应位于 mod 之外，以确保它们在非预构建配置场景中执行。

开始使用