Introduction
您已经有一个渐进式网络应用。它在浏览器中工作，具有清单，并且可能使用服务工作器来支持离线功能。如果您现在需要在应用商店中分发应用程序、原生设备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
在运行之前 bunx cap init, 确认您的Web应用已准备就绪：
- 确保您的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(或您选择的插件)
对于每个新本机插件：
- 安装插件包
- 配置插件特定设置
- Run:
bunx cap sync然后重建并再次运行。
第 7 步：应用商店平行性检查
在提交之前：
- 在两种平台上测试深度链接和路由（
/和深度路由） - 验证状态栏、安全区域和方向正确性
- 移除不必要的 Web-only 元数据，例如安装提示，这与应用行为冲突
- 保持应用传输安全和隐私设置与您的政策一致
- 为每个平台添加应用图标/启动画面资源
如果您的应用程序使用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和移动团队提供一个单一的部署路径，
从这个流程开始，然后根据分析和用户反馈逐步迭代原生功能，
继续从PWA转换为原生应用的流程Capacitor
如果您正在使用 使用Capacitor转换PWA为原生应用 来规划迁移和企业运营，连接它与 Capgo企业 为Capgo企业中的产品工作流程 Ionic企业插件替代方案 为 Ionic Enterprise Plugin 的替代品工作流程 Capgo Alternatives 为 Capgo Alternatives 的工作流程 Capgo 咨询 为 Capgo 咨询的工作流程，和 Capgo Premium 支持 为 Capgo Premium 支持的工作流程。
