跳转至正文
@capacitor-plus/core 开发者工具 开源

Capacitor+ 核心 Capacitor 插件

Capacitor+ 是 Capacitor 的自动化、始终同步的 fork,会合并社区 PR 并快速发布

安装

bun add @capacitor-plus/core bunx cap sync
npm、pnpm 或 yarn
  • npm install @capacitor-plus/core
  • pnpm add @capacitor-plus/core
  • yarn add @capacitor-plus/core

指南

如何在 Capacitor 中使用 Capacitor+ Core

使用 Capacitor+ (@capacitor-plus) 包

Capacitor+ 是一个自动同步的分支,源自 Capacitor 由以下团队维护 Capgo. 它可以直接替换官方 Capacitor 包,并有一个核心优势: 社区 PR 和修复能更快合并.

为什么需要 Capacitor+

Ionic 团队按照自己的优先级和发布节奏维护 Capacitor。这意味着社区的贡献——bug 修复、改进和新功能——可能要等上数月甚至数年才会被合并,有些甚至永远合不进去。

Capacitor+ 通过以下方式解决这个问题:

  1. 合并来自 Fork 的 PR - 主动合并那些卡在 upstream 队列里的有价值 PR
  2. 持续同步 - upstream Capacitor 的每项变更都会被自动拉取、测试和验证
  3. 快速发布 - 变更通过 CI 后,会自动发布到 npm 的 @capacitor-plus 范围
  4. 社区优先 - 你的贡献很重要,会被优先处理
  5. 安全审查 - 每个变更都会由 AI 分析安全漏洞、破坏性变更和稳定性风险

可用包

包 描述
@capacitor-plus/core 核心运行时库
@capacitor-plus/cli 命令行界面
@capacitor-plus/android Android 运行时
@capacitor-plus/ios iOS 运行时

安装

新建项目

对于新项目,只需使用 Capacitor+ 包替代官方包:

npm install @capacitor-plus/core @capacitor-plus/cli
npm install @capacitor-plus/android  # for Android
npm install @capacitor-plus/ios      # for iOS

然后初始化项目:

npx cap init
npx cap add android
npx cap add ios

从官方 Capacitor 迁移

要将现有项目从官方 Capacitor 迁移到 Capacitor+:

# Remove official packages
npm uninstall @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios

# Install Capacitor+ packages
npm install @capacitor-plus/core @capacitor-plus/cli
npm install @capacitor-plus/android  # if using Android
npm install @capacitor-plus/ios      # if using iOS

由于 Capacitor+ 是可直接替换的包,API 完全相同,因此无需改动 code。import 保持不变:

// These imports work the same with Capacitor+
import { Capacitor } from '@capacitor/core';
import { registerPlugin } from '@capacitor/core';

工作原理

┌─────────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  ionic-team/        │     │  CI/CD           │     │  Claude Code     │     │  npm publish    │
│  capacitor          │────▶│  Pipeline        │────▶│  Security Review │────▶│  @capacitor-plus│
│  (upstream)         │     │  (daily sync)    │     │  (AI analysis)   │     │  packages       │
└─────────────────────┘     └──────────────────┘     └──────────────────┘     └─────────────────┘
  1. 每日同步:GitHub Action 会从以下位置获取最新更改 ionic-team/capacitor
  2. 创建 PR:更改会以 PR 的形式提交到 plus 分支
  3. CI 验证:运行完整测试套件(lint、单元测试、iOS 构建、Android 构建)
  4. Claude Code 审查:AI 驱动的全面安全分析,检查以下问题:
    • 安全漏洞(注入、XSS 等)
    • 破坏性 API 变更
    • 崩溃风险和稳定性问题
    • 数据完整性和隐私问题
    • 恶意 code 模式
  5. 自动合并:仅当 CI 通过且 Claude 批准(未检测到问题)时
  6. 自动发布:新版本已发布到 npm 下的 @capacitor-plus/*

安全审查

每次上游同步都会分析以下问题:

查看 描述
安全 命令注入、XSS、路径遍历、硬编码密钥等。
破坏性变更 已移除/重命名的 API、签名变更、配置格式变更
稳定性 空指针解引用、未处理的异常、竞态条件、内存泄漏
数据安全 数据丢失场景、隐私违规、不安全存储
Code 完整性 混淆的 code、可疑网络请求、后门

如果检测到任何问题,PR 将被标记为需人工审查,且不会自动合并。

想让你的 PR 被合并吗?

PR 卡在官方 Capacitor 仓库?以下是把它合入 Capacitor+ 的方法:

  1. 提交 Issue ,详见 Capacitor+ 仓库 链接到你的上游 PR
  2. 或直接提交 PR 到 plus 分支
  3. 团队会审查代码,运行 CI,如果通过则合并

这样,您和其他人就能立即从您的工作中受益,无需等待上游发布周期。

优势

  • 立即获取卡住的 PR:等待上游合并的社区修复和功能已合并
  • 保持最新:上游修复一旦通过 CI 即可获取
  • 安全优先:每个变更都会审查漏洞和稳定性风险
  • 已验证的发布: 只有同时通过 CI 测试和 AI 安全审查的变更才会被发布
  • 直接替换: 与 Capacitor 相同的 API,只是包作用域不同
  • 你的声音很重要: 提交你自己的 PR,或请求合并指定的上游 PR

示例:Capacitor+ 与插件配合使用

所有官方 Capacitor 插件都能与 Capacitor+ 无缝配合使用:

import { Capacitor } from '@capacitor/core';
import { Camera, CameraResultType } from '@capacitor/camera';
import { Geolocation } from '@capacitor/geolocation';

// Everything works exactly the same
const platform = Capacitor.getPlatform();

const photo = await Camera.getPhoto({
  resultType: CameraResultType.Uri
});

const position = await Geolocation.getCurrentPosition();

Capgo 插件也能与 Capacitor+ 完美配合:

import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

// Use Capgo plugins with Capacitor+
await CapacitorUpdater.notifyAppReady();
await ScreenOrientation.lock({ orientation: 'portrait' });

大功告成!现在你拥有了一个更新更及时的 Capacitor 版本,社区改进也能更快合并进来。你的应用可以直接用上 Bug 修复和新功能,无需等待官方发布周期。

继续阅读:使用 Capacitor+ (@capacitor-plus) 包

如果你正在使用 使用 Capacitor+ (@capacitor-plus) 包 要规划原生插件工作,请将其与 Capacitor+ 有关 Capacitor+ 中的实现细节, Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 关于“添加或更新插件”中的实现细节,以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。

常见问题

Capacitor+ Core 插件常见问题

如何在 Capacitor 应用中安装 Capacitor+ Core 插件?

运行 "bun add @capacitor-plus/core"(或 "npm install @capacitor-plus/core"),再运行 "bunx cap sync",让 iOS 和 Android 项目识别到原生 code。然后在应用 code 中从 "@capacitor-plus/core" 导入。

@capacitor-plus/core 支持 React、Vue 和 Angular 吗?

支持。Capacitor+ Core 是一个 Capacitor 包,因此任何运行在 Capacitor 中的 Web 框架都能用,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capacitor-plus/core 支持哪个 Capacitor 版本?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capacitor-plus/core 是免费开源的吗?

是的。code 的源码已在 GitHub 公开,地址为 https://github.com/Cap-go/capacitor-plus/,也可以从 npm 免费安装。欢迎提交 Bug 报告和 Pull Request。

使用 Capacitor+ Core 的 code 能否不经过 App Store 审核就更新?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

发布 Capacitor+ Core 变更,无需等待应用审核

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo