快速入门

快速入门

bun add @capgo/capacitor-plus
npx cap sync

常见坑点

• 替换所有 @capacitor/* 依赖。
• 迁移后重新生成原生项目。
• 升级前请先阅读发布说明。

新项目安装

您可以使用我们的 AI 辅助安装来安装 Capacitor+。使用以下命令将 Capgo 技能添加到您的 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 `@capacitor-plus/core`, `@capacitor-plus/cli`, `@capacitor-plus/android`, and `@capacitor-plus/ios` packages in my project.

如果您更喜欢手动安装，请运行以下命令安装软件包，并遵循下文中的平台特定说明：

1. 安装核心包

   npm install @capacitor-plus/core @capacitor-plus/cli

2. 添加平台包

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

3. 初始化 Capacitor

   npm

   npx cap init

   pnpm

   pnpm cap init

   yarn

   yarn cap init

   bun

   bunx cap init

4. 添加平台

   npm

   npx cap add android

   pnpm

   pnpm cap add android

   yarn

   yarn cap add android

   bun

   bunx cap add android

   npm

   npx cap add ios

   pnpm

   pnpm cap add ios

   yarn

   yarn cap add ios

   bun

   bunx cap add ios

从官方 Capacitor 迁移

如果您已有现有的 Capacitor 项目，迁移到 Capacitor+ 非常简单：

1. 移除官方包

   npm uninstall @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios

2. 安装 Capacitor+ 软件包

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

3. 同步您的项目

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

注意

无需对 code 做任何更改！Capacitor+ 的 API 与官方 Capacitor 相同。你的 import 和 code 完全保持不变。

使用情况

由于 Capacitor+ 与 API 兼容，你现有的 code 无需改动即可使用：

import { Capacitor } from '@capacitor/core';
import { registerPlugin } from '@capacitor/core';

// Check platform
const platform = Capacitor.getPlatform();
console.log('Running on:', platform);

// Check if native
if (Capacitor.isNativePlatform()) {
  console.log('Running on native platform');
}

// Register a custom plugin
const MyPlugin = registerPlugin('MyPlugin');

使用官方 Capacitor 插件

所有官方 Capacitor 插件均可无缝运行：

import { Camera, CameraResultType } from '@capacitor/camera';
import { Geolocation } from '@capacitor/geolocation';
import { Storage } from '@capacitor/preferences';

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

// Geolocation
const position = await Geolocation.getCurrentPosition();

// Storage
await Storage.set({ key: 'name', value: 'John' });

使用 Capgo 插件

Capgo 插件与 Capacitor+ 完美兼容：

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

// Live updates
await CapacitorUpdater.notifyAppReady();

// Screen orientation
await ScreenOrientation.lock({ orientation: 'portrait' });

// Flashlight
await CapacitorFlash.toggle();

同步如何工作

┌─────────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  ionic-team/        │     │  CI/CD           │     │  Claude Code     │     │  npm publish    │
│  capacitor          │────▶│  Pipeline        │────▶│  Security Review │────▶│  @capacitor-plus│
│  (upstream)         │     │  (daily sync)    │     │  (AI analysis)   │     │  packages       │
└─────────────────────┘     └──────────────────┘     └──────────────────┘     └─────────────────┘

1. 每日同步：GitHub Actions 会从以下地址获取最新变更 ionic-team/capacitor
2. 创建 PR：更改会以 PR 的形式提交到 plus 分支
3. CI 验证：运行完整测试套件（lint、单元测试、iOS 构建、Android 构建）
4. 安全审查：AI 驱动的分析可检测漏洞和破坏性变更
5. 自动合并：仅当 CI 通过且安全审查批准时
6. 自动发布：新版本已发布到 npm 下的 @capacitor-plus/*

安全审查详情

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

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

注意

如果检测到任何问题，PR 会被标记为人工审查，且不会自动合并。这样能确保你始终获得稳定、安全的发布。

提交 PR

有 PR 卡在官方 Capacitor 仓库？在 Capacitor+ 中即可合并：

1. 提交 Issue ，详见 Capacitor+ 仓库 链接到你的上游 PR

2. 或直接提交 作为 PR 到 plus 分支

3. 团队会审查、运行 CI，若通过则合并

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

常见问题

可以用于生产环境吗？

是的。Capacitor+ 已用于生产应用。每个版本都通过官方 Capacitor 相同的测试套件，外加额外的安全分析。

我的官方插件还能用吗？

是的，所有 @capacitor/* 插件开箱即可与 Capacitor+ 配合使用。

如果上游发布了破坏性变更怎么办？

AI 安全审查会标记破坏性变更供人工复核。合并前，你会看到这些变更的记录。

如何反馈问题？

请在 Capacitor+ GitHub 仓库中提交问题。对于同时影响官方 Capacitor 的问题，我们会协助与上游协调。

可以参与贡献吗？

当然！欢迎提交 PR。你可以直接提交修复，或请求合并特定的上游 PR。

从入门指南继续

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