使用 patch-project

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

重要注意：patch-project 是一个测试功能。

patch-project 是一个 Expo 配置插件和命令行接口 (CLI) 工具，它可以生成并应用补丁，以在运行 npx expo prebuild 后保留本地更改。该工具对希望保留自定义内容而无需了解如何编写配置插件的本地应用开发者非常有用，它能够有效地生成与连续本地生成 (CNG) 配合使用的自动解决方案。

本指南解释了如何使用 patch-project、何时使用以及它的局限性。

🌐 This guide explains how to use patch-project, when to use it, and its limitations.

patch-project 如何工作

🌐 How patch-project works

patch-project 使用一种生成并自动应用补丁的方法，该方法受到 Git 的启发。在你的项目中使用这个命令行工具需要以下步骤：

安装

🌐 Installation

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

🌐 To get started, you need to install the tool in your project:

Terminal

- npx expo install patch-project

此命令将自动将 patch-project 配置插件添加到你的应用配置中：

🌐 This command will automatically add the patch-project config plugin to your app config:

app.json

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

从现有自定义项生成补丁

🌐 Generate patches from existing customizations

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

🌐 Let's assume you manually modified native directories (android and ios) in your project. To generate patches for these native directories, you can run the following command:

Terminal

- npx patch-project

信息注意：在希望为特定平台生成补丁的情况下，你可以使用 --platform 选项，并运行 npx patch-project --platform android 或 npx patch-project --platform ios。

这些补丁在生成后会保存在 cng-patches 目录中。

🌐 These patches, when generated, are saved in the cng-patches directory.

.

app.jsonwith patch-project plugin

cng-patches

android+eee880ad7b07965271d2323f7057a2b4.patchpatch for android directory

ios+eee880ad7b07965271d2323f7057a2b4.patchpatch for ios directory

package.json

...other project files

每个文件都会以平台名称开头，后跟一个校验和值。例如：

🌐 Each file will be prefixed with a platform's name followed by a checksum value. For example:

ios+eee880ad7b07965271d2323f7057a2b4.patch

在预构建期间应用补丁

🌐 Apply patches during prebuild

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

🌐 Once you have generated patches, they are automatically applied when subsequently running the npx expo prebuild command. The patch-project config plugin detects the existing patches and applies them to restore your customizations.

何时使用 patch-project

🌐 When to use patch-project

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

🌐 You can use patch-project in the following scenarios:

迁移现有的 React Native 应用很复杂，因为它们包含大量本地自定义，而将这些本地自定义重新创建为配置插件将非常耗时。
在将你的 Expo 项目过渡到使用连续本地生成 (CNG) 时，保留对 android 和/或 ios 目录所做的手动更改。
快速原型当你需要在编写配置插件之前测试本地更改时。
补丁会在随后运行 npx expo prebuild 命令时自动应用。这是相比于像 patch-package（常用于为 npm 库生成补丁）这样的工具的一个优势，因为它们在预构建过程中无法保留并自动应用补丁。

限制和注意事项

🌐 Limitations and considerations

补丁在 Expo SDK 版本升级期间可能会失效，原因如下：

🌐 Patches may become invalid during Expo SDK version upgrades because:

模板和/或文件结构变化：预构建模板会随着 SDK 版本的升级而发生变化，在本地目录中引入新的更改和文件更新。这将影响 cng-patches 目录中已生成的差异，可能导致其不再适用。
插件冲突：CNG 补丁可能很危险，当其他插件修改相同文件时，可能会导致补丁失效。例如，如果你添加了一个新的插件，该插件更新了 MainApplication.kt 并与现有补丁冲突，那么补丁可能无法正确应用。在这种情况下，你可能需要重新生成补丁。
iOS .pbxproj 变更：在 iOS 项目中，对 .pbxproj 文件应用补丁可能比较脆弱，因为该文件包含 UUID，像 npx expo prebuild --clean 这样的命令可能会改变这些 ID。例如，如果你正在添加小部件扩展或进行其他项目配置更改，基于补丁的方法可能无法可靠地工作。你可以查看生成的 cng-patches/ios-* 并只保留必要的补丁。保持补丁尽可能精简可以减少应用补丁时失败的风险。

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

🌐 It is recommended to regenerate patches after each SDK upgrade.