简介
你已经有一个渐进式 Web 应用（PWA）。它能在浏览器中运行，有 manifest，可能还用 service worker 做离线支持。如果你现在需要上架应用商店、使用原生设备 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 的 Mac （仅限 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使用应用名称、Bundle ID 和 Web 输出目录运行 Capacitor init：
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 步：迁移后的原生功能增强
在这里，你可以按需将仅 Web 的功能替换为原生 API：
- 推送通知 ->
@capacitor/push-notifications - 安全键值存储 ->
@capacitor/preferences - 相机 / 媒体 ->
@capacitor/camera - 生物识别认证 ->
@capacitor-community/native-biometric（或你选择的插件）
对于每个新的原生插件：
- 安装插件包
- 配置插件专属设置
- 运行：
bunx cap sync然后重新构建并再次运行。
步骤 7：应用商店一致性检查
提交前：
- 在两个平台上测试 deep links 和路由（
/以及 deep routes）。 - 验证状态栏、安全区域（safe areas）和屏幕方向是否正确。
- 移除未使用且与 App 行为冲突的 Web 专用元数据（例如安装提示）。
- 保持 App 传输安全和隐私设置与你的策略一致。
- 为每个平台添加 App 图标和启动屏资源。
如果你的 App 使用 OTA 更新，请将发布 pipeline 与原生安全的更新策略配合使用，并考虑 Capgo 进行受控发布和回滚。
最终检查清单
- Web 应用构建无报错 (
bun run build) - Capacitor 已用正确的配置初始化
webDir bunx cap add ios以及bunx cap add android已完成- 原生应用可在真机上运行
- 仅浏览器端的 code 路径已针对原生行为做限制
- 更新通道和应用商店素材已配置
构建 PWA 时，你已经完成了大部分重活。用 Capacitor 封装后，你可以获得：
- 应用商店分发，
- 访问原生 API，
- 无需完整重写 code，就能更快迭代，
- 为 Web 和移动端团队提供统一的部署路径。
从这条流程开始，再根据数据分析和用户反馈，逐个原生功能迭代。
继续阅读：使用 Capacitor 将 PWA 转换为原生应用
如果你正在使用 使用 Capacitor 将 PWA 转换为原生 App 要规划迁移和企业运营，请将其与 Capgo 企业版 用于 Capgo Enterprise 中的产品工作流， Ionic Enterprise 插件替代方案 用于 Ionic Enterprise 插件替代方案的产品工作流， Capgo 替代方案 用于 Capgo 替代方案的产品工作流， Capgo 咨询 适用于 Capgo Consulting 的产品工作流，以及 Capgo 高级支持 适用于 Capgo Premium Support 的产品工作流。
