将 PWA 转换为本机应用程序与 Capacitor

简介

您已经有一个渐进式网络应用。它在浏览器中工作，具有清单，并且可能使用服务工作器来支持离线功能。如果您现在需要在应用商店中分发应用，使用本机设备API，或者改善引导流程，迁移到一个Capacitor应用通常比重写前端更快。

最大的优势是您可以保留大部分现有的网络code。在大多数情况下，您只需要：

构建生产网络资产，
初始化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

在运行之前，请确保您的Web应用是生产就绪的： bunx cap init步骤2：将您的PWA包装在原生应用中

确保您的PWA有一个生产构建脚本（例如， bun run build).
确认您的Web输出文件夹是确定性的（通常是 dist, build，或 out).
移除假设浏览器上下文的硬编码绝对重定向。
验证服务工作者行为与移动WebViews兼容：
- 如果有助于您的用户，请保留离线支持。
- 避免在嵌入式Web视图中不可用的浏览器仅API。
确认PWA安装提示和浏览器特定用户体验仍然合理。在一个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 以使用您的应用名称、捆绑 ID 和 Web 输出目录:

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

如果您的构建文件夹是 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: 迁移后本机增强

这是您在需要时用本机 API 替换 Web-only 功能的地方：

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

对于每个新本机插件：

安装插件包
配置插件特定设置
然后重建并再次运行。

bunx cap sync

步骤 7: 应用商店平行性检查

提交之前：

在两种平台上测试深度链接和路由（

和深度路由）/ 验证状态栏、安全区域和方向正确性。
移除不必要的 Web-only 元数据，冲突了应用行为（例如，安装提示）。
保持应用传输安全和隐私设置与您的政策一致。
为每个平台添加应用图标/启动画面资产。
Verify that your app meets the requirements for the App Store.

如果您的应用程序使用OTA更新，建议将发布管道与原生安全的更新策略配对，并考虑 Capgo 控制回滚和回滚。

最终检查表

Web应用程序构建干净（bun run build)
Capacitor webDir
bunx cap add ios 使用正确的 bunx cap add android 和
完成
Browser-only code paths are gated for native behavior
仅浏览器__CAPGO_KEEP_0__路径被阻止以原生行为

You already did most of the hard work when building your PWA. Wrapping it with Capacitor gives you:

在各个商店中进行分布
访问本机API
不需要完全重写code，就能实现更快的迭代
为web和移动团队提供一个单一的部署路径

从这个流程开始，然后根据分析和用户反馈逐步迭代native

继续从PWA转换为本机应用程序的流程Capacitor

如果您正在使用 继续从PWA转换为本机应用程序的流程Capacitor 来规划迁移和企业运营，连接它与 Capgo Enterprise 为Capgo Enterprise中的产品工作流程 Ionic Enterprise插件替代品 Ionic 企业插件替代方案的产品工作流程 Capgo替代方案 for the product workflow in Capgo Alternatives, Capgo咨询 Ionic 企业插件替代方案的产品工作流程，包括Capgo咨询 Capgo高级支持 Ionic 企业插件替代方案的产品工作流程，包括Capgo高级支持

Capacitor让您的PWA变成原生应用

简介