手帐 Blog

主题

03 · Capacitor 入门：Web 进原生壳 ​

目标：把现有 Web 构建产物同步进 Android / iOS 工程；说清与纯 PWA 的边界（商店分发 vs 浏览器安装）。

1. 背景与目标 ​

PWA 解决「浏览器里可安装」。Capacitor 解决：同一套 Web 静态资源，装进系统 WebView，以原生 App 身份进商店，并用插件调用相机、文件系统等原生能力。

text
Vite/Vue/React build → dist/
       ↓ npx cap sync
android/ 与 ios/ 原生工程里的 Web 资源更新
       ↓ Android Studio / Xcode
安装包 / 真机调试

本篇只做到：脚手架 + add 平台 + sync + 跑起来。插件与签名发布见 04。

2. 核心概念 ​

概念含义
Web 层你的 H5 构建产物（HTML/JS/CSS）
Native 层android/、ios/ 工程；系统 WebView 加载本地或远程 Web
capacitor.configappId、appName、webDir（指向构建输出目录）
cap synccopy Web 资源 + update 原生依赖 / 插件
与 CordovaCapacitor 是现代继任思路；新项目优先 Capacitor 官方文档

与纯 PWA 边界 ​

维度PWACapacitor
安装入口浏览器「添加到主屏幕」应用商店 / 侧载 APK
运行容器浏览器（有无独立窗口看 display）独立 App 进程 + WebView
原生 API浏览器 Web API（能力因平台而异）官方/社区插件 → 原生代码
审核无商店审核有商店审核与证书
更新SW / 重新访问（也可热更 Web 层，需自建策略）商店发版；Web 层可 sync 后发版

不是二选一：很多产品 H5 做 PWA，商店包用 Capacitor 包同一套 dist。

3. 最小实践 ​

以 Vite + 任意前端框架为例（与 02 的 demo 可衔接）。官方也提供 npm init @capacitor/app；下面按「已有 Web 项目」路径写。

bash
# 在已有前端项目根目录
pnpm build
pnpm add @capacitor/core @capacitor/cli
pnpm add @capacitor/android
# 有 Mac 再加：pnpm add @capacitor/ios
npx cap init

cap init 时填：

  • App name：展示名
  • App ID：如 com.example.pwademo（反域，全局唯一）
  • webDir：Vite 默认 dist

核对 capacitor.config.ts（或 .json）：

ts
import type { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.pwademo',
  appName: 'PWA Demo',
  webDir: 'dist',
}

export default config

添加平台并同步：

bash
pnpm build
npx cap add android
npx cap sync
npx cap open android

在 Android Studio 选模拟器或真机 Run。
iOS 需 macOS + Xcode：npx cap add ios; npx cap sync; npx cap open ios。

日常迭代：改 Web → pnpm build → npx cap sync → 再在 IDE Run（或 npx cap run android）。

Live Reload（开发期把 WebView 指到本机 dev server）见官方「Live Reload」；真机需同一局域网，防火墙放行端口。

4. 踩坑与取舍 ​

  1. webDir 指错：sync 了空目录或旧目录，App 白屏——先确认 pnpm build 输出路径。
  2. 用 file:// 思维调 API：Capacitor 6+ 常用自定义 scheme；CORS / cookie 行为与浏览器 localhost 不同。
  3. 只测 Chrome、不测 WebView：部分 CSS、安全区、键盘顶起在 WebView 才爆。
  4. 把 Capacitor 当「免原生」：进商店仍要证书、隐私清单、权限说明；04 展开。
  5. 与 uni-app App：都是「多端出包」，但工程模型不同——阶段 C 对照；本篇先把「Web 进壳」跑通。

5. 验收清单 ​

  • [ ] capacitor.config 的 appId / webDir 正确
  • [ ] cap add android（或 ios）成功，工程可在 IDE 打开
  • [ ] 改一处 Web 文案 → build → sync → 真机/模拟器看到更新
  • [ ] 能口述 PWA vs Capacitor 在分发与容器上的差异（1 分钟）
  • [ ] （可选）试过 Live Reload 或记下「为何暂时不用」

6. 下一步 ​

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

参考链接 ​