模组

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

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

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

使用下方的图示，在本指南中，你将了解 config plugin 层级结构的最后两部分：

Mod 插件

Mod 插件提供了一种在 prebuild 过程中修改原生项目文件的方法。它们由 expo/config-plugins 库提供，并封装了顶层 mods（也称为 默认 mods），因为顶层 mods 具有平台特定性，并且会执行一些一开始可能难以理解的任务。

提示： 如果你正在开发一个需要 mods 的功能，你应该使用 mod 插件，而不是直接与顶层 mods 交互。

可用的 mod 插件

expo/config-plugins 库中提供了以下 mod 插件：

Android

iOS

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

Mods

Config plugins 使用 mods（即 modifiers，修改器的缩写）在 prebuild 过程中修改原生项目文件。Mods 是异步函数，允许你修改 AndroidManifest.xml、Info.plist 以及其他原生配置文件，而无需手动编辑它们。它们只会在 npx expo prebuild（prebuild 过程）的 同步 阶段执行。

它们接收一个 config 和一个 data 对象，然后将两者修改后作为一个对象一起返回。例如，在原生项目中，mods.android.manifest 会修改 AndroidManifest.xml，而 mods.ios.plist 会修改 Info.plist。

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

Mod 插件如何工作

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

modResults

modResults 对象包含需要修改并返回的数据。它的类型取决于当前使用的 mod。

modRequest

modRequest 对象包含 mod 编译器提供的以下额外属性。

创建你自己的 mod

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

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;
    }
  );
};

// 用法：

/// 创建一个 config
const config = {
  name: 'my app',
};

/// 使用该插件
export default withCustomProductName(config, 'new_name');

插件模块解析

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

1. 在你的 app 项目中定义的插件：这些插件本地存在于你的项目中，因此很容易与应用代码一起自定义和维护。它们非常适合项目特定的自定义。

2. 独立包插件：这些插件作为单独的包存在，并发布到 npm。这种方法非常适合可复用插件，可以在多个项目之间共享。

这两种方法都能提供修改原生配置的相同能力，但在结构和导入方式上有所不同。下面的部分会解释每种方法的模块解析机制。

任何未在下面指定的解析模式都属于非预期行为，且可能会发生破坏性变更。

在你的 app 项目中定义的插件

对于在你的 app 项目中定义的插件，你可以通过几种方式直接在项目中实现插件：

文件导入

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

在上面的示例中，config plugin 文件只包含一个最小函数：

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

动态 app config 内的内联函数

Expo 配置对象也支持按原样将函数传递给 plugins 数组。这对于测试很有用，或者当你想在不创建文件的情况下使用插件时也很有帮助。

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

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

用函数而不是字符串的一个注意事项是，序列化会把函数替换为函数名。这样可以让清单文件（有点像你应用的 index.html）按预期工作。下面是序列化后的 config 看起来的样子：

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

独立包插件

提示 查看 使用 config plugin 创建模块，获取创建独立包插件的分步指南。

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

1. 专用 config plugin 包

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

2. 带伴随包的 config plugin

当某个 config plugin 是一个没有 app.plugin.js 的 Node 模块的一部分时，它会使用该包的 main 入口点：

插件解析顺序

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

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

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

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

错误 避免直接导入模块内部，因为这会绕过标准解析顺序，并且可能在未来更新中失效。

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

对于 config plugins，更倾向于使用 app.plugin.js 方案，因为它允许与主包代码使用不同的转译设置。这一点尤其重要，因为 Node 环境通常需要与 Android、iOS 或 web JS 环境不同的转译预设（例如使用 module.exports 而不是 import/export）。