用 Capacitor 将 PWA 转换为原生 App

简介

你已经拥有了一个 PWA（渐进式 Web 应用）。它可以在浏览器中运行，拥有 manifest 文件，可能还使用了 service worker 来支持离线访问。如果你现在需要通过 App Store 分发、调用原生设备 API 或构建更好的 onboarding 漏斗，那么迁移到 Capacitor 应用通常比重写前端要快得多。

最大的优势在于你可以保留几乎所有的现有 Web code。在大多数情况下，你只需要：

build 生产环境的 Web 资源，
用正确的配置初始化 Capacitor webDir,
添加 iOS 和 Android 项目，
并仅在需要的地方接入原生插件。

如果你的 PWA 路由和组件逻辑清晰，整个过程仅需几小时。

前提条件

预计耗时：2-5 小时，取决于平台特定功能。

Node.js 18+ 及 Bun
你现有的 PWA 源码 code（React、Vue、Angular、Svelte 等）
Xcode (仅限 iOS 和 macOS)
Android Studio (适用于 Android)
若计划发布 iOS 应用，需准备 Apple Developer 账号
若需在 Android 分发，需准备 Google Play Developer 账号

步骤 1：封装成原生应用前先检查你的 PWA

运行前 bunx cap init，请确认您的 Web 应用已达到生产环境标准：

确保您的 PWA 拥有生产环境构建脚本 (例如， bun run build).
确认您的 Web 输出目录是确定的 (通常为 dist, build，或者 out).
移除那些假设仅在浏览器环境下运行的硬编码绝对重定向。
验证 Service Worker 的行为是否与移动端 WebView 兼容：
- 如果对用户有帮助，请保留离线支持功能。
- 避免使用嵌入式 WebView 中不可用的浏览器专属 API。
确认 PWA 安装提示和浏览器特有的 UX 是否仍然合理。在 Capacitor 应用中，通常不需要应用安装提示。

步骤 2：适配仅限 Web 的行为

保留你的应用 UI，但要隔离仅限浏览器的逻辑。

在安装和推送提示处加一个简单的平台判断：

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()

function registerInstallPrompt() {
  if (isNative) return
  // existing browser-only install or Web Push code
}

这样可避免浏览器专属逻辑在原生容器内触发。

步骤 3：在 PWA 目录中初始化 Capacitor

在现有的 PWA 根目录下：

bun add @capacitor/core
bun add -D @capacitor/cli

运行 Capacitor init，并传入应用名称、Bundle ID 和 Web 输出目录：

bunx cap init MyPWAApp com.example.my-pwa-app --web-dir dist

如果你的 build 文件夹是 build (Create React App) 或 out (Next.js 静态导出)，替换 dist.

添加基础 Capacitor 配置：

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

const config: CapacitorConfig = {
  appId: 'com.example.my-pwa-app',
  appName: 'MyPWAApp',
  webDir: 'dist',
  server: {
    iosScheme: 'https',
  },
}

export default config

步骤 4：添加原生平台

安装核心原生包并生成项目文件夹：

bun add @capacitor/ios @capacitor/android
bunx cap add ios
bunx cap add android

此时 Capacitor 已创建 ios/ 和 android/ 文件夹。同步操作会将构建好的 Web 资源复制到两个平台中。

步骤 5：构建 Web 应用并同步

构建 PWA 并同步 Web 资源：

bun run build
bunx cap sync

现在打开原生项目：

bunx cap open ios
bunx cap open android

在 Xcode 或 Android Studio 中，连接设备或模拟器并运行。

第 6 步：迁移后的原生功能增强

在此阶段，您可以根据需要将仅限 Web 的功能替换为原生 API：

推送通知 -> @capacitor/push-notifications
安全键值存储 -> @capacitor/preferences
摄像头 / 媒体 -> @capacitor/camera
生物识别认证 -> @capacitor-community/native-biometric (或您选择的其他插件)

对于每一个新的原生插件：

安装插件包
配置插件特定设置
运行：

bunx cap sync

然后重新构建并运行。

第 7 步：应用商店一致性检查

提交前：

在两个平台上测试深度链接和路由（/ 以及深层路由）。
验证状态栏、安全区域和屏幕方向是否正确。
移除与 App 行为冲突的 Web 端专用元数据（例如安装提示）。
确保 App 传输安全和隐私设置与您的政策保持一致。
为每个平台添加 App 图标和启动页资源。

如果您的 App 使用 OTA 更新，请将发布流水线与原生安全的更新策略相结合，并考虑 Capgo 进行受控发布和回滚。

最终检查清单

Web 应用构建顺利 (bun run build)
Capacitor 已使用正确的配置初始化 webDir
bunx cap add ios 和 bunx cap add android 已完成
Native 应用可在真实设备上运行
仅限浏览器的 code 路径已针对原生行为进行隔离
更新通道和 App Store 资源已配置完毕

在构建 PWA 时，您已经完成了大部分繁重的工作。使用 Capacitor 进行封装后，您可以获得：

应用商店分发能力、
原生 API 的访问权限、
无需完整 code 重写即可实现更快的迭代、
为 Web 和移动端团队提供统一的部署路径。

从这个流程开始，然后根据数据分析和用户反馈，逐个原生功能迭代。

继续阅读《使用 Capacitor 将 PWA 转换为原生 App》

如果你正在使用 用 Capacitor 将 PWA 转换为原生 App 规划迁移与企业运营，并将其与 Capgo 企业版了解 Capgo 企业版的产品工作流， Ionic Enterprise 插件替代方案了解 Ionic Enterprise 插件替代方案中的产品工作流， Capgo 替代方案适用于 Capgo Alternatives 的产品工作流， Capgo 咨询适用于 Capgo Consulting 的产品工作流，以及 Capgo 高级支持适用于 Capgo Premium Support 的产品工作流。