手帐 Blog

主题

04 · Capacitor 插件与双端打包发布 ​

目标：建立插件心智；走通 Android / iOS 本地构建要点；整理签名与调试踩坑清单（不上架流水账）。

1. 背景与目标 ​

03 把 Web 塞进壳。真实 App 还要：调原生能力 + 打出可安装包。
本篇偏工程清单：知道查哪份官方文档、本地先打出 debug/release，而不是背完整上架教程。

2. 核心概念 ​

2.1 插件模型 ​

text
JS:  import { Camera } from '@capacitor/camera'
        ↓ Capacitor bridge
Native: Android / iOS 实现
类型例子注意
官方插件Camera、Filesystem、Preferences、SplashScreen、StatusBar版本与 @capacitor/core 对齐
社区插件各 npm 包看维护状态与 Capacitor 大版本
自定义插件业务独占原生能力需原生同学或自学 Kotlin/Swift

安装后必须 npx cap sync，否则原生侧没有依赖。

权限：Android AndroidManifest.xml、iOS Info.plist 用途字符串；商店审核会看「为什么要相机」。

2.2 构建形态 ​

平台日常调试发布向
AndroidAndroid Studio Run / cap run android签名 AAB（Play）或 APK（国内商店常见）
iOSXcode Run（需证书/模拟器）Archive → App Store Connect

Web 层更新仍走：pnpm build → npx cap sync → 再打原生包。

3. 最小实践 ​

3.1 装一个官方插件（示例：Preferences） ​

bash
pnpm add @capacitor/preferences
npx cap sync
js
import { Preferences } from '@capacitor/preferences'

await Preferences.set({ key: 'theme', value: 'dark' })
const { value } = await Preferences.get({ key: 'theme' })

在真机/模拟器验证（浏览器里部分插件是 web 实现或 no-op，勿只在 Chrome 里以为原生通了）。

3.2 Android 本地打包要点 ​

  1. Android Studio 打开 android/
  2. Build → Generate Signed Bundle / APK（或 Gradle assembleRelease）
  3. 准备 keystore；密码与 jks 进密码管理器，勿提交 Git
  4. applicationId 与 capacitor.config 的 appId 保持一致认知
  5. release 打开 minify 时，注意 WebView / 反射相关 keep 规则（出问题再查官方 troubleshooting）

调试技巧：chrome://inspect 可调试 WebView 里的页面（设备需 USB 调试）。

3.3 iOS 本地打包要点（需 Mac） ​

  1. Xcode 打开 ios/App
  2. Signing & Capabilities：Team、Bundle Identifier
  3. 真机需开发者账号；模拟器可先跑通 UI
  4. Product → Archive 再分发
  5. 隐私权限文案：缺 NSCameraUsageDescription 等会直接崩或拒审

3.4 发布前自检清单（精简） ​

  • [ ] 生产 API 地址不是 localhost
  • [ ] 启动页 / 图标 / 应用名正确
  • [ ] 权限只申请用到的；Info.plist / Manifest 说明齐全
  • [ ] 深色模式、安全区、键盘遮挡抽测过
  • [ ] 版本号 versionCode / CFBundleVersion 递增规则想清楚

4. 踩坑与取舍 ​

  1. 装了插件忘 sync：JS 报插件未实现。
  2. keystore 丢失：无法更新已上架应用——备份优先于「先打出包再说」。
  3. HTTP 明文：Android 默认拦 cleartext；开发代理与正式 HTTPS 分开配置。
  4. 热更新 Web 层：可以，但要自建校验与回滚；商店政策与安全自负。
  5. 复杂手势 / 列表性能：WebView 上限在那；不够再评估 RN（阶段 D），勿过早重写。

5. 验收清单 ​

  • [ ] 至少一个官方插件在模拟器或真机调用成功
  • [ ] Android 能打出 debug 安装包（或 IDE Run 成功）
  • [ ] 能口述 release 签名的必要性与 keystore 保管
  • [ ] （有 Mac）Xcode 工程能 Run 到模拟器
  • [ ] 写下 3 条本机踩坑（权限 / sync / 白屏等任选）

6. 下一步 ​

→ 05 · uni-app 多端打包全景：H5 / 小程序 / App

参考链接 ​