Mods

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

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

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 插件

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 Project 的“产品名称”，你将创建一个使用 withXcodeProject mod 插件的 config 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;
    }
  );
};

// 用法：

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

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

插件模块解析

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

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

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

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

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

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

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

文件导入

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

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

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

动态 app config 内的内联函数

Expo config 对象也支持按原样将函数传递给 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 module 的一部分时，它会使用该包的 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）。