Mods

了解模块以及如何在创建配置插件时使用它们。

本指南解释了什么是 mod 和 mod 插件、它们的工作原理以及如何在为你的 Expo 项目创建配置插件时有效地使用它们。

🌐 This guide explains what mods and mod plugins are, how they work, and how to use them effectively when creating config plugins for your Expo project.

在本指南中，通过下图，你将了解配置插件层次结构的后两部分：

🌐 Using the diagram below, in this guide, you will learn the last two parts of the config plugin hierarchy:

模组插件

🌐 Mod plugins

Mod 插件提供了一种在预构建过程中修改原生项目文件的方法。它们可以通过 expo/config-plugins 库获得，并封装了顶层 mod（也称为 默认 mods），因为顶层 mod 是特定于平台的，并执行各种任务，这些任务一开始可能很难理解。

🌐 Mod plugins provide a way to modify native project files during the prebuild process. They are made available from expo/config-plugins library and wrap top-level mods (also known as default mods) because top-level mods are platform-specific and perform various tasks that can be difficult to understand at first.

信息 提示： 如果你正在开发需要模组的功能，你应使用 模组插件，而不是直接与顶层模组交互。

可用的 mod 插件

🌐 Available mod plugins

expo/config-plugins 库中可用的以下模块插件：

🌐 The following mod plugins are available in the expo/config-plugins library:

安卓

🌐 Android

iOS

信息 关于默认 Android 和 iOS 模组的说明：
默认模组由模组编译器提供，用于常见的文件操作。危险的修改依赖正则表达式（regex）来修改应用代码，这可能会导致构建失败。正则表达式模组也难以进行版本管理，因此应谨慎使用。始终优先使用应用代码来修改应用代码，也就是 Expo Modules 的原生 API。

Mods

配置插件使用 mods（modifier的缩写）在预构建过程中修改原生项目文件。Mods 是异步函数，允许你更改特定平台的文件，例如 AndroidManifest.xml 和 Info.plist，以及其他原生配置文件，而无需手动编辑它们。它们仅在 npx expo prebuild 的 同步 阶段（预构建过程）执行。

🌐 Config plugins use mods (short for modifiers) to modify native project files during the prebuild process. Mods are asynchronous functions that allow you to make changes to platform-specific files such as AndroidManifest.xml and Info.plist, and other native configuration files without having to manually edit them. They execute only during the syncing phase of npx expo prebuild (prebuild process).

它们接受一个配置对象和一个数据对象，然后修改并将它们作为一个整体返回。例如，在原生项目中，mods.android.manifest 会修改 AndroidManifest.xml，而 mods.ios.plist 会修改 Info.plist。

🌐 They accept a config and a data object, then modify and return both of them as a single object. For example, in native projects, mods.android.manifest modifies AndroidManifest.xml and mods.ios.plist modifies Info.plist.

你不能在你的配置插件中直接将模块作为顶层函数使用（例如 with.android.manifest）。 当你需要使用某个模块时，你应在配置插件中使用_模块插件_。这些模块插件由 expo/config-plugins 库提供，它们封装了顶层模块函数，并在后台执行各种任务。要查看可用模块列表，请查看 expo/config-plugins 提供的模块插件。

模组插件的工作原理

🌐 How mod plugins work

当一个 mod 插件被执行时，它会被传入一个带有额外属性 modResults 和 modRequest 的 config 对象。

🌐 When a mod plugin is executed, it gets passed a config object with additional properties: modResults and modRequest.

modResults

modResults 对象包含要修改和返回的数据。它的类型取决于正在使用的 mod。

🌐 The modResults object contains the data to modify and return. Its type depends on the mod that's being used.

modRequest

modRequest 对象包含由模块编译器提供的以下附加属性。

🌐 The modRequest object contains the following additional properties supplied by the mod compiler.

创建你自己的模组

🌐 Create your own mod

例如，如果你想编写一个用于更新 Xcode 项目“产品名称”的 mod，你需要创建一个使用 withXcodeProject mod 插件的配置插件文件。

🌐 For example, if you want to write a mod to update the Xcode Project's "product name", you'll create a config plugin file that uses the withXcodeProject mod plugin.

import { ConfigPlugin, withXcodeProject, IOSConfig } from 'expo/config-plugins';

const withCustomProductName: ConfigPlugin<string> = (config, customName) => {
  return withXcodeProject(
    config,
    async (
      config
    ) => {
      config.modResults = IOSConfig.Name.setProductName({ name: customName }, config.modResults);
      return config;
    }
  );
};

// Usage:

/// Create a config
const config = {
  name: 'my app',
};

/// Use the plugin
export default withCustomProductName(config, 'new_name');

插件模块解析

🌐 Plugin module resolution

在实现插件时，有两种基本方法需要考虑：

🌐 When implementing plugins, there are two fundamental approaches to consider:

1. 在你的应用项目中定义的插件：这些插件存储在项目本地，使其可以轻松地与应用代码一起自定义和维护。它们非常适合特定项目的定制化需求。
2. 独立包插件：这些插件以独立包的形式存在，并发布到 npm。对于可以在多个项目中共享的可复用插件，这种方式是理想的选择。

这两种方法在修改本地配置时提供相同的功能，但在结构和导入方式上有所不同。下面的章节解释了每种方法的模块解析是如何工作的。

🌐 Both approaches provide the same capabilities for modifying your native configuration, but differ in how they're structured and imported. The sections below explain how module resolution works for each approach.

任何未在下文指定的解析模式都属于意外行为，可能会发生破坏性更改。

在你的应用项目中定义的插件

🌐 Plugins defined within your app's project

在你的应用项目中定义插件后，你可以通过多种方式直接在项目中实现插件：

🌐 With plugins defined within your app's project, you can implement plugins directly in your project in several ways:

文件导入

🌐 File import

你可以通过创建一个 JavaScript/TypeScript 文件快速在你的项目中创建插件，并像使用其他 JS/TS 文件一样在配置中使用它。

🌐 You can quickly create a plugin in your project by creating a JavaScript/TypeScript file and use it in your config like any other JS/TS file.

在上面的示例中，配置插件文件包含一个最基本的函数：

🌐 In the above example, the config plugin file contains a bare minimum function:

module.exports = ({ config }: { config: ExpoConfig }) => {};

动态应用配置中的内联函数

🌐 Inline function inside of dynamic app config

Expo 配置对象也支持将函数原样传递到 plugins 数组中。这对于测试很有用，或者如果你想使用插件而不创建文件时也很方便。

🌐 Expo config objects also support passing functions as-is to the plugins array. This is useful for testing, or if you want to use a plugin without creating a file.

const withCustom = (config, props) => config;

const config = {
  plugins: [
    [
      withCustom,
      {
        /* props */
      },
    ],
    withCustom,
  ],
};

使用函数而不是字符串的一个注意事项是，序列化会将函数替换为函数的名称。这可以保持 清单（有点像你应用的 index.html）按预期工作。下面是序列化配置的示例:

🌐 One caveat to using functions instead of strings is that serialization will replace the function with the function's name. This keeps manifests (kind of like the index.html for your app) working as expected. Here is what the serialized config would look like:

{
  "plugins": [["withCustom", {}], "withCustom"]
}

独立包插件

🌐 Standalone package plugins

信息 请参阅 使用配置插件创建模块 获取有关如何创建独立包插件的分步指南。

独立软件包插件可以通过两种方式实现：

🌐 Standalone package plugins can be implemented in two ways:

1. 专用配置插件包

🌐 1. Dedicated config plugin packages

这些是 npm 包，其唯一目的是提供配置插件。对于专用的配置插件包，你可以使用 app.plugin.js 导出你的插件：

🌐 These are npm packages whose sole purpose is to provide a config plugin. For a dedicated config plugin package, you can export your plugin using app.plugin.js:

2. 使用配套软件包配置插件

🌐 2. Config plugins with companion packages

当配置插件是 Node 模块的一部分且没有 app.plugin.js 时，它使用该包的 main 入口点：

🌐 When a config plugin is part of a Node module without an app.plugin.js, it uses the package's main entry point:

插件解析顺序

🌐 Plugin resolution order

当你导入插件包时，文件将按以下特定顺序解析：

🌐 When you import a plugin package, files are resolved in this specific order:

1. 包根目录中的 app.plugin.js

2. 包的主入口（来自 package.json）

3. 直接内部导入（不推荐）

错误 避免直接导入模块的内部内容，因为这会绕过标准解析顺序，并可能在将来更新中导致破坏。

为什么使用 app.plugin.js 插件

🌐 Why use app.plugin.js for plugins

app.plugin.js 方法更适合用于配置插件，因为它允许与主包代码不同的转译设置。这一点尤为重要，因为 Node 环境通常需要与 Android、iOS 或网页 JS 环境不同的转译预设（例如，使用 module.exports 而不是 import/export）。

🌐 The app.plugin.js approach is preferred for config plugins as it allows different transpilation settings from the main package code. This is particularly important because Node environments often require different transpilation presets compared to Android, iOS, or web JS environments (for example, module.exports instead of import/export).