介绍
您已经有一个渐进式网络应用程序。它在浏览器中工作，有一个清单，可能使用服务工作器来支持离线支持。如果您现在需要在应用商店中分发应用程序、原生设备 API 或更好的引导流程，迁移到 Capacitor 应用程序通常比重写前端更快。
最大的优势是您可以保留大部分现有的网络 code。在大多数情况下，您只需要：
- build production web assets,
- 初始化 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 包装在原生应用之前，检查您的 PWA
在运行之前，请确认您的 Web 应用是生产就绪的： bunx cap init确保您的 PWA 有一个生产构建脚本（例如
- 确认您的 Web 输出文件夹是确定性的（通常
bun run build). - 或
dist,build__CAPGO_KEEP_0__out). - 移除假设浏览器环境的绝对重定向。
- 验证服务工作人员行为与移动WebViews兼容：
- 如果有助于您的用户，保持离线支持。
- 避免在嵌入式Web视图中不可用的浏览器仅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与您的应用名称、包ID和Web输出目录：
bunx cap init MyPWAApp com.example.my-pwa-app --web-dir dist如果你的构建文件夹是 build (Create React App) 或 out (Next.js 静态导出)，请替换 dist.
Add a basic Capacitor config:
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安装核心原生包并生成项目文件夹：
到目前为止，__CAPGO_KEEP_0__ 已创建
bun add @capacitor/ios @capacitor/android
bunx cap add ios
bunx cap add androidAt this point Capacitor has created ios/ 文件夹。同步会将你的构建的 Web 资产复制到两个平台。 android/ 步骤 5：构建 Web 应用并同步
构建 PWA 并同步 Web 资产：
现在打开原生项目：
bun run build
bunx cap sync如果你的构建文件夹是
bunx cap open ios
bunx cap open android从 Xcode 或 Android Studio 中连接设备或模拟器并运行。
第 6 步：迁移后本机增强
这是您在需要时用本机 API 替换仅在 Web 上可用的功能的地方：
- 推送通知 ->
@capacitor/push-notifications - 安全的键值存储 ->
@capacitor/preferences - 相机 / 媒体 ->
@capacitor/camera - 生物识别认证 ->
@capacitor-community/native-biometric(或选择的插件)
对于每个新本机插件：
- 安装插件包
- 配置插件特定的设置
- 运行:
bunx cap sync然后重建并再次运行。
第 7 步：应用商店平衡检查
提交之前：
- 在两种平台上测试深度链接和路由（
/和深度路由） - 确认状态栏、安全区域和方向正确。
- 移除未使用的 Web-only 元数据，这些元数据与应用行为冲突（例如，安装提示）。
- 保持应用传输安全和隐私设置与您的政策一致。
- 为每个平台添加应用图标/启动画面资产。
如果您的应用使用 OTA 更新，请将您的发布管道与原生安全的更新策略配对，并考虑 Capgo 用于控制回滚和回滚。
最终检查清单
- Web 应用程序构建干净（
bun run build) - Capacitor 使用正确的
webDir bunx cap add ios和bunx cap add android完成- 本机应用程序在真实设备上运行
- 仅浏览器code路径被阻止以获得本机行为
- 更新频道和应用商店资产已配置
您已经完成了大部分困难的工作，当您构建您的PWA时。将其包装在Capacitor中给您：
- 商店分发
- 访问本机API
- 不需要重新编写code的更快迭代
- A single deployment path for web and mobile teams.
Start from this flow, then iterate native-by-native based on analytics and user feedback.
