capacitor-apple-review-preflight

Capacitor Apple 审核预检

在提交前或遭拒后，对 Capacitor 应用进行 Apple 审核审计，并返回一份按优先级排序、有证据支持的报告。

此技能改编自 truongduy2611/app-store-preflight-skills 中的 Apple 指南和拒绝规则语料库，并将工作流限定为 Capacitor 专属项目检查。

适用场景

在以下情况触发：

• 用户希望对 Capacitor 应用进行 App Store 审核预检。
• 用户收到 App Review 拒绝通知或 App Store Connect 上传警告邮件，并希望审计项目。
• 用户询问元数据、权利、隐私清单、Sign in with Apple、订阅、AI 功能或最低功能要求是否能通过审核。
• 用户希望为 Capacitor 提交准备审核备注（演示账户、实时更新、硬件功能）。

以下情况不要使用：

• Google Play 政策或 Data safety -> capacitor-app-store（Android 参考）。
• 归档、上传、屏幕截图、TestFlight -> capacitor-app-store。
• 从头开始让网站具有原生应用体验 -> webapp-to-capacitor。
• 超出审核规则范围的安全加固 -> capacitor-security。

实时项目快照

检测到的 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 sections=['dependencies','devDependencies'];const out=[];for(const section of sections){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/')||name.startsWith('@capgo/')||name.includes('firebase')||name.includes('sentry')||name.includes('revenuecat')||name.includes('purchase')||name.includes('subscription')||name.includes('auth')||name.includes('analytics')||name.includes('segment')||name.includes('amplitude')||name.includes('mixpanel')||name.includes('openai')||name.includes('anthropic')||name.includes('gemini'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

相关 Apple 审核文件路径： !find . -maxdepth 6 -not -path '*/node_modules/*' \( -name 'package.json' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -name 'Info.plist' -o -name '*.entitlements' -o -name 'PrivacyInfo.xcprivacy' -o -name 'SceneDelegate.swift' -o -name 'project.pbxproj' -o -path './ios' -o -path './fastlane/metadata' -o -path './metadata' \)

当前 Apple 要求（2026 年 10 月）

先检查以下事项；它们会在审核开始前导致上传失败：

• SDK：自 2026 年 4 月 28 日起，上传的构建版本必须使用 Xcode 26+ / iOS 26 SDK。从 2027 年 4 月起，必须使用 iOS 27 SDK（Xcode 27）。
• UIScene：Xcode 27 构建版本要求使用场景生命周期。Capacitor 8.5+ 支持此功能；应用需要 SceneDelegate.swift、Info.plist 中的 UIApplicationSceneManifest，以及 AppDelegate 中的 configurationForConnecting。启用后，AppDelegate 的 application(_:open:options:)、continue userActivity 和前台/后台回调将不再触发；其中的自定义原生代码必须移至场景代理。
• 隐私清单：对于应用代码使用的必需理由 API，应用目标需要有自己的 PrivacyInfo.xcprivacy；Apple 隐私影响列表中的 SDK 必须提供各自的清单和签名（Capacitor core 和 CapacitorCordova 自带清单）。
• 年龄分级：必须填写更新后的问卷（4+、9+、13+、16+、18+），否则无法提交新版本。
• AI 数据共享：指南 5.1.2(i)（2025 年 11 月修订）要求在应用内明确披露，并在将个人数据发送给第三方 AI 服务前征得明确许可。

流程

第 1 步：确认范围

仅处理面向 Apple 审核的工作。如果任务主要涉及发布流程，请转交给 capacitor-app-store。如果用户引用了拒绝理由，优先检查对应指南，然后再扩展到相邻风险。

步骤 2：识别应用类型并加载检查清单

始终阅读 references/guidelines/by-app-type/all_apps.md。然后添加匹配的检查清单：

应用包含	加载
订阅或 IAP	subscription_iap.md
UGC、聊天、社交动态	social_ugc.md
儿童类别	kids.md
健康、健身、医疗声明	health_fitness.md
游戏	games.md
AI / LLM 功能	ai_apps.md
加密货币、交易、金融	crypto_finance.md
VPN / 网络	vpn.md
也发布到 macOS	macos.md

如果拒绝理由引用了特定章节，请使用 references/guidelines/README.md 查看完整的指南索引。

步骤 3：检查 Capacitor 和 iOS 项目

从快照开始，然后阅读：

• package.json，检查身份验证、分析、广告、支付、AI SDK。
• capacitor.config.*，检查 appId、server.url（发布版本中的远程 server.url 存在 4.2 / 2.5.2 风险）以及实时更新配置。
• ios/App/App/Info.plist：检查插件可能触发的每个 NS...UsageDescription、ITSAppUsesNonExemptEncryption、UIApplicationSceneManifest、UIBackgroundModes。
• *.entitlements 与实际发布的功能是否匹配。
• PrivacyInfo.xcprivacy（应用目标成员资格、必需原因 API、跟踪域名）。
• 如有，检查 fastlane/metadata 或 metadata/。

Capacitor 特有风险：

• 仅使用 WebView，且没有原生价值或移动端体验 -> 4.2。
• 远程 server.url 加载网站 -> 4.2 和 2.5.2。
• 社交登录没有 Sign in with Apple 或等效的私密选项 -> 4.8。
• iOS 版本中显示用于数字商品的网页结账 -> 3.1.1。
• 使用实时更新更改应用用途，或添加超出审核范围的功能 -> 指南 2.5.2 和 Apple Developer Program License Agreement 中对解释执行代码的条款；披露更新机制，并将更新限制为 Web 资源修复。
• Info.plist 中存在插件权限，但描述含糊或照搬而来 -> 5.1.1。
• 在 Xcode 中启用但未使用的功能（Push、iCloud、HealthKit、Associated Domains）。

步骤 4：运行基于规则的检查

规则文件是事实依据：

• 元数据：references/rules/metadata/*.md
• 订阅：references/rules/subscription/*.md
• 隐私：references/rules/privacy/*.md
• 设计：references/rules/design/*.md
• 权限：references/rules/entitlements/*.md
• 构建：references/rules/build/sdk_and_scene_lifecycle.md（Xcode/SDK 最低要求、UIScene）

将元数据规则对应到 App Store 文本、屏幕截图、预览和审核备注；将隐私规则对应到 Info.plist、清单、SDK 和数据流；将设计规则对应到导航、原生价值和登录；将权限规则对应到已启用的功能。

如果元数据不在本地，且已配置 asc CLI，请使用 asc metadata pull --output-dir ./metadata 拉取。否则，审核本地来源，并将元数据检查标记为部分完成。

步骤 5：报告

## Apple Review Preflight

### Rejections Found
- [GUIDELINE X.X.X] Issue summary
  - Evidence: file:line or metadata field
  - Why it matters for this Capacitor app
  - Fix: exact remediation

### Warnings
- [GUIDELINE X.X.X] Potential issue

### Passed
- [Category] Checks that looked clean

### Missing Inputs
- Metadata or assets not available locally

按严重程度排序。在进行影响较大的更改（移除功能、更改身份验证或账单）之前先报告；遇到这些决策点时，询问用户。

步骤 6：审核备注和后续事项

起草以下事项的备注：演示帐户、隐藏功能或依赖硬件的功能、订阅测试路径、AI 审核和数据共享同意、实时更新行为（仅 Web 资源；无原生更改），以及特殊权限或后台模式的原因。

验证

• 每项拒绝问题都已应用具体修复，或明确指定负责人/决策。
• plutil -lint ios/App/App/Info.plist ios/App/App/PrivacyInfo.xcprivacy 通过。
• PrivacyInfo.xcprivacy 属于 App 目标成员（检查 project.pbxproj 中的 Resources 构建阶段是否包含该文件）。
• grep -c "UsageDescription" ios/App/App/Info.plist 的结果与插件可能请求的权限相符。
• 发布版本可在 Xcode Organizer 中归档并验证，且没有 ITMS 警告。
• 演示帐户可在全新安装后登录生产后端。

错误处理

输入	操作
ITMS-91053“缺少 API 声明”，并附有类别名称	在应用清单中添加对应的 NSPrivacyAccessedAPIType 和获批原因（references/rules/privacy/privacy_manifest.md）
ITMS-91061“缺少隐私清单”，并指出某个 SDK	将 SDK／插件更新到捆绑了清单的版本；不要将 SDK 的实践复制到应用清单中
ITMS-90683“缺少用途说明字符串”	添加所指出的键，并填写具体的用途说明字符串
封装应用因指南 4.2 被拒	按最高严重级别处理；列出具体的原生功能和 UX 差距；绝不能只回复审核人员的备注
指南 4.8	添加“通过 Apple 登录”（@capgo/capacitor-social-login 支持 apple），或添加符合 4.8 标准的等效选项
指南 5.1.1(v)	添加应用内账户删除功能（不能只有支持邮箱）
元数据不可用且缺少 asc	继续进行代码审计；将元数据检查标记为部分完成
第三方 SDK 表明需要使用必需理由 API	在假定符合要求前，检查每个 SDK 捆绑的清单