webapp-to-capacitor

Web 应用转为 Capacitor 应用

将生产环境中的 Web 应用转为 Capacitor 应用，使其表现得像移动应用并通过应用商店审核。搭建 Capacitor 外壳通常只需一天；移动端 UX、原生功能和应用商店政策才是真正的工作重点。

适用场景

满足以下情况时使用：

• “把我的网站 / PWA / React（Vue、Angular、Svelte、Next.js、Nuxt）应用转成 iOS/Android 应用。”
• 用户询问 Apple 是否会拒绝 WebView 外壳（准则 4.2），或如何让应用更有原生体验。
• 用户需要涵盖权限、离线、身份验证、账户删除、付款和测试的迁移计划。

以下情况请勿使用：

• 仅修复特定框架的 webDir、SSR 或路由问题 -> framework-to-capacitor。
• Cordova/PhoneGap/Ionic-Cordova 项目 -> cordova-to-capacitor。
• 上传构建产物、屏幕截图、应用商店页面元数据 -> capacitor-app-store。
• 审核提交内容或答复拒绝决定 -> capacitor-apple-review-preflight。
• CI 流水线和签名 -> capacitor-ci-cd 或 capgo-native-builds。

实时项目概况

检测到的 Web 框架、构建脚本和 Capacitor 软件包： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const names=['@capacitor/core','@capacitor/cli','@capacitor/ios','@capacitor/android','@capgo/capacitor-updater','next','react','vue','@angular/core','@sveltejs/kit','nuxt','vite','@ionic/react','@ionic/vue','@ionic/angular','vite-plugin-pwa','workbox-window'];const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(names.includes(name))out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/build|dev|preview|start|export|generate|sync|cap|ios|android/i.test(name))out.push('scripts.'+name+'='+cmd)}console.log(out.sort().join('\n'))"

相关配置和原生项目路径： !find . -maxdepth 4 -not -path '*/node_modules/*' \( -name 'capacitor.config.*' -o -name 'vite.config.*' -o -name 'next.config.*' -o -name 'nuxt.config.*' -o -name 'angular.json' -o -name 'svelte.config.*' -o -name 'manifest.webmanifest' -o -name 'manifest.json' -o -path './ios' -o -path './android' -o -name 'Info.plist' -o -name 'AndroidManifest.xml' \)

命令策略

安装依赖和运行脚本时，使用目标仓库的包管理器。Capacitor 和 Capgo CLI 示例始终使用 npx cap ... 和 npx @capgo/cli@latest ...。

流程

1. 审核（更改任何内容前先报告）

整理简要清单并展示给用户：

• 框架、版本、构建输出目录。
• 仅限服务端的功能：SSR、API 路由、中间件、服务端操作、图片优化、与 Web 源站绑定的基于 Cookie 的会话。
• 身份验证：身份提供商、Cookie 会话还是令牌会话、OAuth 重定向 URI（仅适用于 Web 的重定向在应用中会失效）。
• 付费内容：销售的内容。在应用中消费的数字商品/订阅需要使用 Apple IAP / Google Play Billing，除非适用特定豁免或权益（阅读器应用、外部购买链接权益、地区规则）。实体商品和现实世界服务仍使用 Web 付款方式。
• 产品所需的原生功能：相机、照片、文件、推送通知、位置、生物识别、触觉反馈、分享、后台工作。
• 离线需求以及必须保存在本地的数据。
• 应在应用中打开的链接（通用链接 / 应用链接）。
• PWA 组件：Service Worker、Web manifest、beforeinstallprompt UI。

需要向用户确认的判断事项：如果应用除了网站本身别无其他功能，请直言，并建议在投入应用商店提交工作前加入具体的原生价值（推送通知、离线功能、相机流程，之后还可加入小组件）。

2. 静态构建

让应用生成 index.html 和资源，无需 Node 服务。加载 framework-to-capacitor 以使用框架专属配置。将仅限服务端的逻辑移至托管 API，使其可从 capacitor://localhost（iOS）和 https://localhost（Android）来源访问（CORS），或使用 CapacitorHttp。

3. Capacitor 外壳

npm install @capacitor/core @capacitor/ios @capacitor/android
npm install -D @capacitor/cli
npx cap init "App Name" com.company.app --web-dir dist
npx cap add ios
npx cap add android
npm run build && npx cap sync

• 使用 Capacitor 8.5+（当前稳定版）。它提供了 Xcode 27 所需的 iOS UIScene 生命周期。Capacitor 9 目前仅在 next 标签下提供。
• 新项目默认在 iOS 上使用 SPM；请保留此设置（预计 CocoaPods Trunk 将于 2026 年 12 月 2 日转为只读）。
• Cookie：网站中的 localStorage/Cookie 不会沿用；应用的来源是新的。请为重新登录做好准备。
• 在应用构建中禁用 Service Worker，或严格限制其作用范围；它可能会固定使用过时的资源包。
• 在应用内移除“安装此应用”PWA 提示和网页下载链接。

4. 原生体验的 UX（4.2 的防御措施）

• 安全区域和 Android 全屏显示 → safe-area-handling。
• 键盘遮挡输入框 → capacitor-keyboard。
• 启动画面、图标、启动状态 → capacitor-splash-screen。
• 平台导航：标签栏/堆栈、Android 硬件返回按钮（App.addListener('backButton', ...)）、iOS 上的边缘滑动返回、不依赖悬停操作的控件，以及 44pt/48dp 的触控目标。
• 使用离线和错误状态，而非浏览器错误页面 → capacitor-offline-first。
• 外部链接应在系统浏览器或 @capacitor/browser 中打开，而不是在应用的 WebView 中打开。
• 如有需要，可使用 UI 工具包 → ionic-design、konsta-ui、tailwind-capacitor。

5. 原生功能

优先使用官方 @capacitor/* 插件；官方插件未覆盖的功能再使用 @capgo/*（参见 capacitor-plugins）。对于每个插件：

• 添加 iOS 使用说明（NS...UsageDescription），明确说明具体且真实的用途。
• 仅在需要时添加 Android 权限；在实际使用时再请求，切勿在首次启动时一次性请求所有权限。
• 在 UI 中处理拒绝、受限和不可用状态。
• 在真实设备上测试。

6. 账户和付款

• 在应用中创建账户，必须同时支持在应用内删除账户（Apple 5.1.1(v)；Google Play 也要求提供删除途径和网页链接）。
• iOS 上的第三方/社交登录：检查准则 4.8（使用 Apple 登录或提供具有同等隐私保护的选项）。
• 数字商品：通过 @capgo/native-purchases 进行 IAP（参见 subscription-app-revenue），或使用获批的替代方案；在不允许的 iOS 构建中，隐藏数字商品的网页结账功能。

7. 应用商店准备

• Apple：自 2026 年 4 月 28 日起，上传的应用必须使用 Xcode 26 / iOS 26 SDK 构建；自 2027 年 4 月起，必须使用 iOS 27 SDK（Xcode 27）。使用 Xcode 27 构建时需要 UIScene 生命周期（Capacitor 8.5+）。隐私清单（PrivacyInfo.xcprivacy）和 App Privacy 问卷的答案必须与实际 SDK 行为一致。提供演示账户和审核备注。运行 capacitor-apple-review-preflight。
• Google Play：自 2026 年 8 月 31 日起，新应用和更新必须以 API 36 为目标（Capacitor 8 模板以 36 为目标）。完成 Data safety、内容分级和应用访问权限信息（提供演示凭据）。2023 年 11 月 13 日后创建的个人开发者账户，必须先进行封闭测试，至少有 12 名选择加入的测试人员连续参与 14 天，才能获得正式发布权限；请尽早安排测试人员。
• 然后使用 capacitor-app-store 提交。

8. 实时更新（外壳正常工作后再提供）

除非项目禁止实时更新，否则提供 Capgo：

npx @capgo/cli@latest init
npx @capgo/cli@latest bundle upload --channel production

请明确说明限制：实时更新只能更改 Web 资源。原生代码、插件、权限、entitlements、图标、签名和应用商店元数据仍需通过应用商店发布更新。详情见 capgo-live-updates；托管原生构建见 capgo-native-builds。

验证

• npm run build 会生成 <webDir>/index.html；npx cap sync 完成且不会出现缺少插件的警告。
• 在 iOS 模拟器和 Android 模拟器上启动并进入第一个屏幕；然后在每个平台的实体设备上测试每个原生插件。
• 应用中的登录、登出、账户删除、购买／恢复购买、离线模式和深度链接均正常工作。
• 每次完成关键流程后，强制关闭应用并重新启动；切换到后台再恢复后，状态应保持不变。
• Safari Web Inspector / chrome://inspect 中没有 CORS 错误，也没有发往 localhost: 的请求。
• 检查应用构建所用的 grep -rn "beforeinstallprompt\|navigator.serviceWorker.register" src。

错误处理

症状／错误	修复方法
The web assets directory (./dist) must contain an index.html file.	未配置静态构建；请参阅 framework-to-capacitor
OAuth 登录循环或出现 redirect_uri_mismatch	Web 重定向 URI 在应用中无法使用；请使用原生提供商 SDK（@capgo/capacitor-social-login）或自定义 scheme／通用链接重定向
API 调用仅在设备上失败（blocked by CORS policy）	允许 capacitor://localhost 和 https://localhost 来源，或启用 CapacitorHttp
应用因 4.2 Minimum Functionality 被拒	增加原生价值和移动端 UX；在审核备注中说明原生功能；请参阅 capacitor-apple-review-preflight
应用因 3.1.1 被拒	在 IAP 之外进行数字商品购买；改用 IAP，或从 iOS 构建中移除相关功能
Play Console：生产轨道已锁定	完成 12 名测试者／14 天的封闭测试（个人账户）
Play 上传因目标 API 级别被拒	将 targetSdkVersion 提高到当前要求（自 2026 年 8 月 31 日起为 API 36）
部署后仍显示旧版 bundle	服务工作线程缓存；在应用构建中禁用 SW

输出格式

对于规划任务，请返回：

## Migration Plan
### App Fit
- Framework / build output:
- Server-only features to move:
- Native capabilities:
- Money (IAP vs web):
- Store risks:
### Phases
1. Static build  2. Capacitor shell  3. Native UX  4. Plugins + permissions  5. Accounts + payments  6. Store readiness  7. Live updates
### Verification
- Local / iOS / Android / Store

对于实施任务，请完成更改、运行检查，并将设备测试和商店政策方面的不足与本地构建状态分开报告。