capacitor-plugins

Capacitor 插件

选择合适的插件，正确安装，并确认它已原生链接。

适用场景

在以下情况使用：

• 用户询问“实现 X 应该使用哪个插件？”或比较不同插件选项。
• 用户需要原生功能（相机、文件、位置、生物识别、支付、身份验证、传感器、存储、媒体、日历、联系人、健康、本地设备上的大模型）。
• 插件安装后调用失败："X" plugin is not implemented on ios|android|web、UNIMPLEMENTED、unable to find plugin 或 OS-PLUG-* 错误代码。
• 用户需要了解插件所需的 Info.plist / AndroidManifest.xml / variables.gradle 条目。

以下情况请勿使用（改用相应的相邻技能）：

• 推送通知设置、FCM/APNs 密钥：capacitor-push-notifications
• 启动画面资源和时序：capacitor-splash-screen
• 键盘遮挡、附件栏、调整大小：capacitor-keyboard
• Universal Links / App Links：capacitor-deep-linking
• OTA 实时更新：capgo-live-updates
• 跨 Capacitor 主版本迁移插件源代码：capacitor-plugin-upgrades（以及 capacitor-plugin-upgrade-v8-to-v9）
• 为插件添加 Swift Package Manager 支持：capacitor-plugin-spm-support；将应用迁移到 SPM：cocoapods-to-spm
• AppDelegate/SceneDelegate 生命周期变更：capacitor-uiscene-migration
• 升级应用的 Capacitor 主版本：capacitor-app-upgrades
• SQL 存储迁移：sqlite-to-fast-sql

版本信息（2026 年 10 月）

• Capacitor 稳定版：8.5.x（latest）。Capacitor 9 在 next dist-tag 上的版本为 9.0.0-alpha。官方插件版本随之发布：大多数 v8 插件在 latest 上为 8.x，在 next 上为 9.0.0-alpha。
• 插件主版本必须与应用的 Capacitor 主版本匹配。旧主版本的插件使用 latest-<major> 标签，例如 npm install @capacitor/camera@latest-7。
• 部分官方插件使用独立版本（file-transfer 2.x、file-viewer 2.x、inappbrowser 4.x、privacy-screen 2.x、barcode-scanner 3.x、background-runner 3.x、calendar/contacts/health-fitness 1.x）。请检查 npm view <pkg> peerDependencies，不要只看版本号来匹配。
• @capgo/* 插件使用与 Capacitor 主版本相同的自身主版本（Capacitor 8 对应 8.x）。部分软件包提供 lts-v7 等 LTS 标签。
• Capacitor 9：iOS 最低版本为 16，Android 的 minSdk 为 26。此前需要设置 minSdkVersion = 26 的插件（inappbrowser、barcode-scanner）不再需要提高 minSdk。

操作流程

1. 先检查。 查看 package.json（@capacitor/core 版本）、capacitor.config.*，并确认 iOS 使用 SPM（ios/App/CapApp-SPM/Package.swift）还是 CocoaPods（ios/App/Podfile）。运行 npx cap ls，查看已链接的插件。

2. 选择软件包。

   • 如果存在满足需求的官方 @capacitor/* 软件包：默认选择它。查阅下方索引中的参考资料。
   • 如果没有官方软件包，或它缺少所需功能：加载 references/capgo-plugin-index.md，选择确切的 @capgo/* 名称。说明它为何更合适。
   • 未先运行 npm view <pkg> version 检查前，切勿推荐参考文件中未列出的软件包名称。

3. 安装匹配主版本的软件包：

   npm install @capacitor/<name>        # or @capgo/<name>
   npx cap sync
   

4. 添加参考资料中的原生配置：用途说明键、清单权限、variables.gradle 中的 minSdk/库版本、功能/授权，以及 AppDelegate 钩子。缺少 iOS 用途说明字符串会导致应用在首次访问时崩溃。

5. 提高 minSdkVersion、添加授权（HealthKit、Push）或启用精确闹钟前，先征求用户同意：这些操作会影响商店审核和设备覆盖范围。

6. 验证（见下一节），然后在真实设备上运行涉及相机、健康、大模型、BLE 或推送的功能。

Capgo 插件索引

references/capgo-plugin-index.md 是完整的 Capgo 插件来源，基于 Cap-go GitHub 的 package.json 和 src/definitions.ts 生成，包含每个公开且未归档软件包的 npm 名称、用途、安装命令、平台、主要 API 方法、文档和仓库链接。references/capgo-plugin-catalog.md 是同一组插件的精简表格。推荐任何 @capgo/* 软件包之前，先加载索引并使用其中的准确名称。

Cap-go 组织发生变化后重新生成这两个文件（仅限仓库维护者）：

GITHUB_TOKEN=$(gh auth token) node scripts/generate-capgo-plugin-index.mjs

验证

npx cap sync              # must finish without "[error]" lines
npx cap ls                # lists "Found N Capacitor plugins for ios/android"; plugin must appear for each platform

• Android：android/app/capacitor.build.gradle 中包含 implementation project(':capacitor-<name>')，且 android/capacitor.settings.gradle 中有匹配的 include。然后运行 cd android && ./gradlew assembleDebug。
• iOS SPM：ios/App/CapApp-SPM/Package.swift 中列出了插件软件包。iOS CocoaPods：ios/App/Podfile 中包含 pod，且 pod install 已成功运行。在 Xcode 中构建，或运行 npx cap run ios。
• 替换插件时，使用 grep 查找残留内容：grep -rn "<old-package>" src android ios package.json。
• 在运行时检测功能：Capacitor.isPluginAvailable('Camera') 和 Capacitor.getPlatform()。

错误处理

错误	原因	修复方法
"Camera" plugin is not implemented on ios（或 android/web）	原生端未链接，或没有 Web 实现	运行 npx cap sync，重新构建原生应用（实时重载不会加载新的原生代码），检查 npx cap ls。在 Web 上，使用 Capacitor.isNativePlatform() 进行保护。
"Camera.takePhoto()" is not implemented on ios	插件已链接，但 JS 和原生版本不同，或该方法仅适用于特定平台	使 JS 和原生版本一致，运行 npx cap sync，然后进行干净构建。查看参考文档，了解仅适用于特定平台的方法。
UNIMPLEMENTED 错误代码	此平台或 OS 版本不支持该方法	根据平台分支处理；请参阅参考文档中的“备注”。
Android 日志 unable to find plugin : X	插件类未注册或未纳入构建	确认 capacitor.build.gradle 条目，重新同步，并在 Android Studio 中执行 Gradle 同步。
iOS 日志 Error loading plugin X for call. Check that the pluginId is correct	插件未包含在 iOS 构建中	重新同步；检查 Package.swift（SPM）或 Podfile；清理构建文件夹。
首次访问相机/联系人/日历/位置时应用崩溃（iOS）	缺少 NS*UsageDescription 键	将参考文档列出的键添加到 Info.plist。
Manifest merger failed : uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library [...]	插件需要更高的 minSdk	提高 android/variables.gradle 中的 minSdkVersion（先询问用户）。
OS-PLUG-* 代码（例如 OS-PLUG-CAMR-0003）	基于 OutSystems 的官方插件中的结构化原生错误	在插件参考文档中查找代码（camera、file-transfer、calendar、contacts 列出了常见代码）。
npm ERESOLVE peer @capacitor/core 冲突	插件主版本与应用主版本不匹配	安装匹配的标签（@latest-7；v9 alpha 使用 @next），或使用 capacitor-app-upgrades 升级应用。

参考索引

仅当相关插件正在使用时才加载参考文档。

官方 @capacitor/* 包（安装、原生配置、用法、注意事项）：

需求	参考文档
操作表	references/capacitor-action-sheet.md
打开其他应用 / 检查是否已安装	references/capacitor-app-launcher.md
应用状态、返回按钮、URL 打开事件	references/capacitor-app.md
后台运行 JS 任务	references/capacitor-background-runner.md
条码 / QR 码扫描	references/capacitor-barcode-scanner.md
适用于 OAuth 的应用内浏览器（SFSafariViewController / Custom Tabs）	references/capacitor-browser.md
日历事件	references/capacitor-calendar.md
相机、图库、视频（8.1+ API、getPhoto 迁移）	references/capacitor-camera.md
剪贴板	references/capacitor-clipboard.md
联系人	references/capacitor-contacts.md
原生 Cookie（核心）	references/capacitor-cookies.md
设备信息 / ID / 电池	references/capacitor-device.md
原生警告框 / 确认框 / 提示框	references/capacitor-dialog.md
带进度的上传 / 下载	references/capacitor-file-transfer.md
打开 / 预览文档	references/capacitor-file-viewer.md
文件读写	references/capacitor-filesystem.md
位置（前台）	references/capacitor-geolocation.md
Google Maps	references/capacitor-google-maps.md
HealthKit / Health Connect	references/capacitor-health-fitness.md
触觉反馈	references/capacitor-haptics.md
原生 HTTP（核心，可绕过 CORS）	references/capacitor-http.md
WebView / 系统浏览器 / 外部浏览器	references/capacitor-inappbrowser.md
键盘 API 基础知识	references/capacitor-keyboard.md
设备端大模型（实验性）	references/capacitor-local-llm.md
本地通知	references/capacitor-local-notifications.md
加速度计 / 方向	references/capacitor-motion.md
网络连接	references/capacitor-network.md
键值存储	references/capacitor-preferences.md
隐藏应用切换器快照 / 阻止截屏	references/capacitor-privacy-screen.md
推送 API 概要	references/capacitor-push-notifications.md
屏幕方向锁定	references/capacitor-screen-orientation.md
TalkBack / VoiceOver 状态、TTS	references/capacitor-screen-reader.md
分享面板	references/capacitor-share.md
启动画面 API 概要	references/capacitor-splash-screen.md
状态栏（旧版）	references/capacitor-status-bar.md
沉浸式系统栏（核心，Android 16+ 推荐）	references/capacitor-system-bars.md
WebView 文本缩放	references/capacitor-text-zoom.md
Toast	references/capacitor-toast.md
Apple Watch UI（实验性）	references/capacitor-watch.md

Capgo 插件：references/capgo-plugin-index.md（145 个包：安装、平台、关键 API、文档）和 references/capgo-plugin-catalog.md（精简表格）。

Capgo 快速选型

需求	包
后台地理定位、地理围栏	@capgo/background-geolocation
自定义相机预览 / 覆盖层	@capgo/camera-preview
生物识别登录 + 安全凭据	@capgo/capacitor-native-biometric
Apple/Google/Facebook 登录	@capgo/capacitor-social-login
订阅 / 应用内购买	@capgo/native-purchases（收入策略：subscription-app-revenue）
Apple Pay / Google Pay	@capgo/capacitor-pay
快速原生 SQLite	@capgo/capacitor-fast-sql
原生文件操作 / 文件选择	@capgo/capacitor-file、@capgo/capacitor-file-picker
支持 JS 注入、postMessage、屏幕截图的应用内浏览器	@capgo/capacitor-inappbrowser
后台运行时被终止并重新启动的 WebView	@capgo/capacitor-webview-guardian
App Attest / Play Integrity	@capgo/capacitor-app-attest
OTA 实时更新	@capgo/capacitor-updater（设置：capgo-live-updates）
开发实时重载	@capgo/capacitor-live-reload

注意事项：

• 如无必要，不要安装两个拥有相同原生功能的插件（例如两个应用内浏览器或两个生物识别插件）；它们可能会在代理和清单条目上发生冲突。
• Firebase：请安装各个 @capgo/capacitor-firebase-* 包；npm 上没有统一的 @capgo/capacitor-firebase 包。
• Cordova 插件仍然可用，但在 Capacitor 9 上会引入 Cordova 运行时；建议优先使用对应的 Capacitor 原生替代方案（cordova-to-capacitor）。

资源

• 官方插件文档：https://capacitorjs.com/docs/apis
• Capgo 插件文档：https://capgo.app/docs/plugins/
• Capgo GitHub：https://github.com/Cap-go