指南
如何在 Capacitor 中使用 Capacitor+ Core
使用 Capacitor+ (@capacitor-plus) 包
Capacitor+ 是一个自动同步的分支,源自 Capacitor 由以下团队维护 Capgo. 它可以直接替换官方 Capacitor 包,并有一个核心优势: 社区 PR 和修复能更快合并.
为什么需要 Capacitor+
Ionic 团队按照自己的优先级和发布节奏维护 Capacitor。这意味着社区的贡献——bug 修复、改进和新功能——可能要等上数月甚至数年才会被合并,有些甚至永远合不进去。
Capacitor+ 通过以下方式解决这个问题:
- 合并来自 Fork 的 PR - 主动合并那些卡在 upstream 队列里的有价值 PR
- 持续同步 - upstream Capacitor 的每项变更都会被自动拉取、测试和验证
- 快速发布 - 变更通过 CI 后,会自动发布到 npm 的
@capacitor-plus范围 - 社区优先 - 你的贡献很重要,会被优先处理
- 安全审查 - 每个变更都会由 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 │
└─────────────────────┘ └──────────────────┘ └──────────────────┘ └─────────────────┘
- 每日同步:GitHub Action 会从以下位置获取最新更改
ionic-team/capacitor - 创建 PR:更改会以 PR 的形式提交到
plus分支 - CI 验证:运行完整测试套件(lint、单元测试、iOS 构建、Android 构建)
- Claude Code 审查:AI 驱动的全面安全分析,检查以下问题:
- 安全漏洞(注入、XSS 等)
- 破坏性 API 变更
- 崩溃风险和稳定性问题
- 数据完整性和隐私问题
- 恶意 code 模式
- 自动合并:仅当 CI 通过且 Claude 批准(未检测到问题)时
- 自动发布:新版本已发布到 npm 下的
@capacitor-plus/*
安全审查
每次上游同步都会分析以下问题:
| 查看 | 描述 |
|---|---|
| 安全 | 命令注入、XSS、路径遍历、硬编码密钥等。 |
| 破坏性变更 | 已移除/重命名的 API、签名变更、配置格式变更 |
| 稳定性 | 空指针解引用、未处理的异常、竞态条件、内存泄漏 |
| 数据安全 | 数据丢失场景、隐私违规、不安全存储 |
| Code 完整性 | 混淆的 code、可疑网络请求、后门 |
如果检测到任何问题,PR 将被标记为需人工审查,且不会自动合并。
想让你的 PR 被合并吗?
PR 卡在官方 Capacitor 仓库?以下是把它合入 Capacitor+ 的方法:
- 提交 Issue ,详见 Capacitor+ 仓库 链接到你的上游 PR
- 或直接提交 PR 到
plus分支 - 团队会审查代码,运行 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 插件替代方案”中的产品工作流。