用Capacitor打造跨平台应用的实战经验与踩坑总结

为啥我要对比这些方案？

最近一个项目要从纯 Web 转成能上 App Store 的混合应用，老板说“别搞太复杂，但得能跑”。我第一反应就是 Capacitor —— 毕竟 Cordova 太老，React Native 又得重写 UI，而我们已经有完整的 Vue 3 + Vite 项目。但问题来了：Capacitor 本身只是个容器，具体怎么调原生能力、怎么处理权限、怎么发通知，其实有好几种路子。折腾了两周，踩了几个坑，今天就来唠唠我实际用下来的感受。

谁更灵活？谁更省事？

Capacitor 官方提供了三种主流方式：

• 直接用官方插件（比如 @capacitor/camera）
• 自己写原生插件（Java/Kotlin + Swift）
• 用社区插件（比如 capacitor-plugin-xxx）

我一开始图省事，全用官方插件。结果在 iOS 上请求定位权限时翻车了——官方 Geolocation 插件居然不自动弹权限框！得手动在 Info.plist 里加描述，而且第一次调用时如果用户点了“拒绝”，后续再调也不会再弹。这体验太差了。后来查文档才发现，官方插件为了“通用性”，很多细节都留白了，得你自己补。

相比之下，我自己写了个极简的定位插件，反而更可控。虽然多写了点原生代码，但能精准控制权限弹窗时机，还能加个“去设置”按钮引导用户手动开启。关键是，只用了不到 50 行 Java 和 30 行 Swift，比想象中简单。

// android/app/src/main/java/com/example/MyLocationPlugin.java
package com.example;

import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;

@CapacitorPlugin(name = "MyLocation")
public class MyLocationPlugin extends Plugin {
    @PluginMethod
    public void requestPermission(PluginCall call) {
        // 这里可以精确控制权限请求逻辑
        if (hasPermission(Manifest.permission.ACCESS_FINE_LOCATION)) {
            call.resolve();
        } else {
            saveCall(call);
            pluginRequestPermission(Manifest.permission.ACCESS_FINE_LOCATION, 123);
        }
    }

    @Override
    protected void handleRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
        super.handleRequestPermissionsResult(requestCode, permissions, grantResults);
        // 处理用户选择后的回调
    }
}

// ios/App/App/MyLocationPlugin.swift
import Foundation
import Capacitor

@objc(MyLocationPlugin)
public class MyLocationPlugin: CAPPlugin {
    @objc func requestPermission(_ call: CAPPluginCall) {
        // iOS 权限逻辑更复杂，但自己写就能塞进自定义提示
        let locationManager = CLLocationManager()
        if locationManager.authorizationStatus == .notDetermined {
            locationManager.requestWhenInUseAuthorization()
        }
        call.resolve()
    }
}

当然，如果你的需求很标准（比如拍照、文件读写），我比较喜欢用官方插件，毕竟省心。但一旦涉及权限、后台任务、系统级交互，官方插件往往“半成品”，这时候自己写反而更稳。

社区插件：香是香，但得看维护状态

npm 上搜 capacitor，一堆第三方插件。比如 capacitor-plugin-bluetooth-le，看起来功能齐全。但我试了两个，一个半年没更新，iOS 16 上直接崩溃；另一个依赖了过时的原生库，build 都过不了。最后还是自己撸了一个精简版。

这里注意我踩过好几次坑：社区插件的文档经常和代码对不上，有的连 TS 类型定义都没有。你 npm install 之后，发现调用时报错“plugin not implemented”，一查才发现它只支持 Android，iOS 得自己补。所以现在我的原则是：优先看 GitHub 最近 commit 时间，超过 3 个月没动静的，直接 pass。

性能对比：差距比我想象的大

很多人以为 Capacitor 就是 WebView 包壳，性能都一样。其实不是。关键差别在“桥接”方式。

官方插件走的是 Capacitor 的标准桥（bridge），数据序列化/反序列化有开销。我自己写的插件如果只传简单参数（比如 boolean、string），基本无感；但如果传大对象（比如 base64 图片），就会卡一下。后来我改用 Filesystem.writeFile 先存临时文件，再传路径，流畅多了。

社区插件更玄学。有个推送插件，每次收到通知都要把整个 payload 转成 JSON 再塞给 JS，结果在低端 Android 机上，连续收 5 条消息，App 直接 ANR。最后我 fork 了它的代码，改成只传必要字段，才解决。

所以我的结论是：高频、大数据量的交互，尽量避免直接传对象，用文件或缓存中转。这点在官方文档里几乎没提，但实战中特别重要。

我的选型逻辑

现在我接到新需求，会按这个流程走：

1. 先看官方插件能不能满足：如果只是标准功能（相机、相册、设备信息），直接用，省时间。
2. 如果官方插件缺关键特性（比如权限控制、后台保活），就自己写最小插件。别怕原生代码，Capacitor 的插件模板很清晰，Android Studio 和 Xcode 也能帮你检查语法。
3. 社区插件只作为备选，而且必须本地跑通 demo 再集成。别信 README，信 logcat 和 Xcode console。

举个例子：我们要做扫码功能。官方 BarcodeScanner 插件在 iOS 上启动慢，而且不能自定义 UI。我试了两个社区插件，一个内存泄漏，一个不支持竖屏。最后自己用 ZXing 写了个 Android 插件 + AVFoundation 写 iOS 插件，虽然花了两天，但启动快、UI 能定制、还能加闪光灯开关——上线后用户反馈“扫码速度比竞品快”。

再比如网络请求，有人建议用 capacitor-plugin-http 替代 fetch，说能绕过 CORS。但实测发现它在 Android 上 SSL pinning 支持不好，而且调试时看不到 Network tab。我现在还是用原生 fetch，CORS 问题让后端配 CORS 头，或者走代理（开发时用 Vite proxy，生产用 Nginx）。别为了“技术炫技”引入额外复杂度。

结尾：没有银弹，只有权衡

Capacitor 的最大优势不是“跨平台”，而是“渐进式增强”。你可以先用 Web 技术快速迭代，等真遇到平台限制时，再针对性地写原生插件。这种模式比 React Native 或 Flutter 更适合已有 Web 项目的团队。

但记住：每个插件都是技术债。自己写的要维护，社区的要盯更新，官方的要读源码。我现在的项目里，原生插件总共就 3 个（定位、扫码、蓝牙），其他全靠官方插件 + Web API，build 一次 2 分钟，CI/CD 也稳。

以上是我踩坑后的总结，希望对你有帮助。有更优的实现方式欢迎评论区交流——比如你们怎么处理 iOS 后台定位的？我还在找靠谱方案……