指南
如何在 Capacitor 中使用 Capacitor+ Core
使用 Capacitor+ (@capacitor-plus) 包
Capacitor+ 是一个自动化的、始终同步的 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: 更改将以 pull request 的形式提交至
plus分支 - CI 验证: 运行全套测试 (lint、单元测试、iOS 构建、Android 构建)
- Claude Code 代码审查: 基于 AI 的全面安全分析，检查以下内容：
- 安全漏洞 (注入、XSS 等)
- 破坏性的 API 变更
- 崩溃风险与稳定性问题
- 数据完整性与隐私问题
- 恶意 code 模式
- 自动合并: 仅在 CI 通过且 Claude 批准 (未检测到问题) 时执行
- 自动发布：新版本已发布至 npm，时间为
@capacitor-plus/*
安全审查
每次上游同步都会分析以下内容：
| 查看 | 描述 |
|---|---|
| 安全 | 命令注入、XSS、路径遍历、硬编码密钥等 |
| 破坏性变更 | 已移除/重命名的 API、签名变更、配置格式变更 |
| 稳定性 | 空指针解引用、未处理的异常、竞态条件、内存泄漏 |
| 数据安全 | 数据丢失、隐私泄露、存储不安全 |
| Code 完整性 | 混淆的 code、可疑的网络请求、后门 |
如果检测到任何问题，该 PR 将被标记为人工审核，且不会自动合并。
想让你的 PR 被合并吗？
在官方 Capacitor 仓库中有卡住的 PR？以下是将其引入 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 插件替代方案”中的产品工作流。