使用 patch-project

了解如何使用 patch-project 在您的 Expo 项目中生成、应用和保留原生更改。

注意: patch-project 是一个实验性功能。

patch-project 是一个 Expo 配置插件和命令行界面 (CLI) 工具，用于生成和应用补丁，以在运行 npx expo prebuild 后保留原生更改。该工具对希望保留自定义的原生应用开发者非常有用，而不需要了解如何编写配置插件，有效地生成与 持续原生生成 (CNG) 兼容的自动解决方案。

本指南解释了如何使用 patch-project、什么时候使用它及其限制。

patch-project 的工作原理

patch-project 采用了一种生成并自动应用补丁的方法，灵感来自 Git。使用该命令行工具需要在您的项目中执行以下步骤：

安装

要开始使用，您需要在您的项目中安装该工具：

此命令将自动将 patch-project 配置插件添加到您的 app config 中：

{
  "expo": {
    "plugins": [
      "patch-project"
      %%placeholder-start%% ...%%placeholder-end%%
    ]
  }
}

从现有自定义生成补丁

假设您手动修改了项目中的原生目录 (android 和 ios)。要为这些原生目录生成补丁，您可以运行以下命令：

注意: 在您想为特定平台生成补丁的情况下，可以使用 --platform 选项并运行 npx patch-project --platform android 或 npx patch-project --platform ios。

生成的补丁将保存在 cng-patches 目录中。

每个文件将以平台的名称前缀，并加上校验和值。例如：

ios+eee880ad7b07965271d2323f7057a2b4.patch

在预构建期间应用补丁

一旦您生成了补丁，它们将在随后的 npx expo prebuild 命令运行时自动应用。patch-project 配置插件会检测现有补丁并将其应用，以恢复您的自定义设置。

何时使用 patch-project

您可以在以下情况下使用 patch-project：

• 迁移现有的 React Native 应用，因为它们包含大量原生自定义，重新创建这些原生自定义作为配置插件将非常耗时。
• 保留手动更改，这些更改是在转向采用持续原生生成 (CNG) 的 Expo 项目中进行的 android 和/或 ios 目录中。
• 快速原型制作，当您需要在编写配置插件之前测试原生更改时。
• 补丁将在随后的 npx expo prebuild 命令运行时自动应用。与 patch-package 等工具相比，这是一个优势（常用于为 npm 库生成补丁），后者在预构建过程中并不会保留和自动应用补丁。

限制和注意事项

在升级 Expo SDK 版本时，补丁可能会失效，因为：

• 模板和/或文件结构更改：预构建模板在 SDK 版本之间演进，带有新的更改和原生目录中的文件更新。这将影响已生成的 cng-patches 目录中的差异，可能不再适用。
• 插件冲突：CNG 补丁可能会很危险，并且当其他插件修改同一文件时可能会出现问题。例如，如果您添加一个新的插件更新 MainApplication.kt 并与现有补丁冲突，则补丁可能无法正确应用。在这种情况下，您可能需要重新生成补丁。
• iOS .pbxproj 更改：在 iOS 项目中，将补丁应用于 .pbxproj 文件可能会很脆弱，因为该文件包含 UUID，运行命令如 npx expo prebuild --clean 可能会更改这些 ID。例如，如果您正在添加小部件扩展或进行其他项目配置更改，基于补丁的方法可能无法可靠工作。您可以查看生成的 cng-patches/ios-* 并仅保留必要的补丁。将补丁保持尽可能小将减少应用补丁时失败的风险。

建议在每次 SDK 升级后重新生成补丁。