快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-patch` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm install @capgo/capacitor-patch
npx cap sync

在 Capacitor 配置中选择 patch 之前，该 package 不会执行任何操作。

快速入门

bun add @capgo/capacitor-patch
npx cap sync

常见坑点

• 在升级 Capacitor 前，请检查版本限制。
• 在执行 cap sync 之前，请先在 CI 中安装。
• 修改 Native 代码后，请重新运行 sync。

选择 patch ID

列出所有已发布的 patch：

npx capgo-capacitor-patch list --all

然后将应用所需的 patch ID 添加到 capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    CapacitorPatch: {
      patches: ['upstream-pr-8418-android'],
      strict: true,
    },
  },
};

export default config;

再次运行 sync：

npx cap sync

Package patches 会在...之前运行 sync 以及 update. Native project patches 会在...之后运行 sync 以及 update.

应用前进行 Dry-run

使用 doctor 以检查所选 patch 是否与已安装的 package 版本匹配：

npx capgo-capacitor-patch doctor --phase package --strict

使用 apply 当你想手动运行所选 patch 时：

npx capgo-capacitor-patch apply --phase package

配置选项

选项	类型	默认	描述
recommended	boolean	false	应用 Capgo 标记为推荐的补丁。
patches	string[]	[]	应用指定的补丁 ID。
disabled	string[]	[]	跳过选定的补丁 ID，即使它们被推荐。
strict	boolean	false	当选定的补丁不兼容或无法应用时抛出错误。

提示

优先使用显式配置 patches 用于生产环境应用，以便在 code 审查中查看已应用的修复。

CLI 命令

npx capgo-capacitor-patch list --all
npx capgo-capacitor-patch doctor
npx capgo-capacitor-patch apply

常用选项：

• --root <dir> 设置应用根目录。
• --phase package|native|all 限制运行哪个 patch 阶段。
• --platform ios|android 在 Capacitor hook 之外应用平台过滤。
• --strict 将选定的 patch 失败视为错误。

工作流

1. 安装 @capgo/capacitor-patch.
2. 运行 npx capgo-capacitor-patch list --all.
3. 将选定的 patch ID 添加到 plugins.CapacitorPatch.patches.
4. 运行 npx capgo-capacitor-patch doctor --strict.
5. 运行 npx cap sync.

当选定的 patch 针对 @capacitor/cli，该 patch 将应用于已安装的 CLI 包以及下一个 cap 命令将使用已打补丁的 CLI code。

从入门指南继续

如果你正在使用 快速入门 要规划原生插件工作，请将其与 使用 @capgo/capacitor-patch 在使用 @capgo/capacitor-patch 时，获取 Native 能力的方法： Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。