capacitor-app-store

将 Capacitor 应用发布到应用商店

让 Capacitor 构建从“在我的设备上能运行”走向“在两个应用商店正式上线”，避免可避免的上传或审核失败。

适用场景

在以下情况下触发：

• 用户正在准备首次发布，或准备向 App Store Connect 或 Google Play Console 发布更新。
• 上传或处理失败（ITMS 错误、Play Console 版本／目标 API 错误）。
• 用户需要截图尺寸、图标要求、上架信息、隐私表单或分阶段发布选项。
• 用户询问应用商店目前要求的 Xcode／SDK 或目标 API 级别。

以下情况请勿使用：

• 审核应用是否符合 App Review Guidelines，或回答审核拒绝相关问题 -> capacitor-apple-review-preflight。
• 编写 GitHub Actions／GitLab／Fastlane 流水线 -> capacitor-ci-cd。
• 在 Capgo Cloud 中构建／签名 -> capgo-native-builds。
• 审核通过后发布仅涉及 Web 的修复 -> capgo-live-updates。

实时项目快照

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 out=['version='+(pkg.version||'')];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/')||name==='@capgo/capacitor-updater'||name==='@capacitor/assets')out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

原生发布文件： !find . -maxdepth 5 -not -path '*/node_modules/*' \( -name 'Info.plist' -o -name 'PrivacyInfo.xcprivacy' -o -name '*.entitlements' -o -name 'SceneDelegate.swift' -o -name 'variables.gradle' -o -name 'build.gradle' -o -name 'ExportOptions.plist' -o -path './fastlane' \)

当前应用商店要求（2026 年 10 月）

要求	详情	对 Capacitor 的影响
Apple SDK 最低要求	自 2026 年 4 月 28 日起：须使用 Xcode 26+ 和 iOS 26 SDK 构建。自 2027 年 4 月起：须使用 iOS 27 SDK（Xcode 27）	Capacitor 8 可使用 Xcode 26 构建；Xcode 27 需要 Capacitor 8.5+ 的项目变更
UIScene 生命周期	使用 Xcode 27／iOS 27 SDK 构建时，必须采用 scene 生命周期	Capacitor 8.5+：添加 SceneDelegate.swift、UIApplicationSceneManifest 和 AppDelegate configurationForConnecting（参见 capacitor-app-upgrades）
隐私清单	必须声明需说明用途的 API；列出的第三方 SDK 必须附带各自已签名的清单	Capacitor 核心和维护中的插件均附带清单；你的应用仍需有自己的 PrivacyInfo.xcprivacy
Apple 年龄分级	全新问卷，包含 13+、16+、18+ 等级；须在 2026 年 1 月 31 日前作答，否则无法提交更新	在 App Store Connect -> App Information -> Age Ratings 中作答
Play 目标 API	自 2026 年 8 月 31 日起，新应用和更新必须以 API 36 为目标（可申请延至 2026 年 11 月 1 日）；目标 API 低于 35 的现有应用将无法触达新设备上的新用户	Capacitor 8 模板使用 compile／target 36；Capacitor 9 使用 37
Play 格式	新应用必须上传 AAB，并启用 Play App Signing	./gradlew bundleRelease
16 KB 页大小	以 Android 15+ 为目标且包含原生 .so 库的应用，必须符合 16 KB 对齐要求	检查 SQLCipher、ML、媒体和分析 SDK
Play 封闭式测试	2023 年 11 月 13 日之后创建的个人账号：正式发布前，须让 12 名或更多测试人员连续 14 天选择加入封闭式测试	提前开始测试

如果用户临近截止日期，请重新核实日期：Apple 会在 developer.apple.com/news/upcoming-requirements 发布信息，Google 会在 developer.android.com/google/play/requirements/target-sdk 发布信息。

流程

1. 阅读快照。确认 Capacitor 版本、iOS 场景生命周期（检查是否存在 SceneDelegate.swift）、variables.gradle 中的 SDK 值，以及是否存在隐私清单。
2. 与用户确定发布路径：手动发布（Xcode Organizer + Play Console）、CLI/CI（capacitor-ci-cd），或 Capgo Cloud Build（capgo-native-builds）。
3. 提升版本号。两个平台上用户可见的版本号必须一致；每次上传的构建号必须严格递增：
   • iOS：在 Xcode 目标构建设置中设置 MARKETING_VERSION（CFBundleShortVersionString）和 CURRENT_PROJECT_VERSION（CFBundleVersion）。Info.plist 通常引用 $(MARKETING_VERSION)/$(CURRENT_PROJECT_VERSION)；应编辑构建设置，而不是 plist 中的字面值。
   • Android：在 android/app/build.gradle 中设置 versionName 和 versionCode（versionCode 上限为 2100000000）。
4. 构建 Web 资源并同步：npm run build && npx cap sync。
5. 加载平台参考文档并遵循其中的说明：references/ios-submission.md、references/android-submission.md。
6. 使用 references/assets-and-metadata.md 准备应用商店素材。
7. 在 iOS 上点击提交之前，对任何非简单更新运行 capacitor-apple-review-preflight。
8. 分阶段发布：iOS 分阶段发布（7 天，可暂停），或使用 Play 分阶段发布百分比；扩大范围前监控崩溃率。

验证

• iOS：在 Xcode Organizer 中归档验证（“Validate App”）且无错误；处理完成后，构建版本会显示在 TestFlight 中；在真实设备上从 TestFlight 安装并运行关键流程。
• Android：通过 bundletool 或 Play 内部测试安装成功；Play Console 预发布报告没有崩溃；aapt2 dump badging app-release.aab 或 Play Console 显示预期的 versionCode 和 targetSdkVersion。
• 两个平台：应用可从商店构建版本冷启动（而非调试构建）；审核员演示账号可以登录；深层链接和推送在发布签名下正常工作。

错误处理

错误	修复方法
ITMS-4238 “Redundant Binary Upload”（构建号已使用）	增加 CURRENT_PROJECT_VERSION
ITMS-90062 CFBundleShortVersionString 必须高于之前获批的版本	增加 MARKETING_VERSION
ITMS-90186 “Invalid Pre-Release Train”（版本序列已关闭）	该营销版本已发布；增加 MARKETING_VERSION
ITMS-90725 “SDK Version Issue”（使用较旧的 SDK 构建）	使用所需的 Xcode/SDK 构建（当前需 Xcode 26+，从 2027 年 4 月起需 Xcode 27）
ITMS-91053 “Missing API declaration”	在 PrivacyInfo.xcprivacy 中添加所需原因 API 类别和原因代码
ITMS-91061 某个具名 SDK “Missing privacy manifest”	将该 SDK/插件更新到包含隐私清单的版本；不要将 SDK 的使用实践复制到应用清单中
ITMS-90683 “Missing purpose string in Info.plist”	添加指定的 NS...UsageDescription，并说明具体用途
使用 Xcode 27 构建后，应用启动时显示黑屏或完全无法启动	尚未采用 UIScene 生命周期；升级到 Capacitor 8.5+，并应用 8.5 项目变更
Play：Version code 45 has already been used. Try another version code.	增加 versionCode
Play：上传时出现目标 API 级别错误	在 variables.gradle 中将 targetSdkVersion/compileSdkVersion 提升到所需级别
Play：You uploaded an APK or Android App Bundle that was signed in debug mode	使用上传密钥构建 bundleRelease
Play：Your Android App Bundle is signed with the wrong key	使用已注册的上传密钥签名，或在 Play Console 中申请重置上传密钥
Play：无法使用正式版轨道	完成 12 名测试者 / 14 天的封闭测试（个人账号）

参考资料

• references/ios-submission.md - 签名、归档、上传选项、TestFlight、App Privacy、出口合规、审核备注、分阶段发布。
• references/android-submission.md - 发布签名、AAB、Play App Signing、发布轨道、Data safety、目标 API 和 16 KB 检查、分阶段推出。
• references/assets-and-metadata.md - 图标生成、截图尺寸、两个应用商店的文本字段限制。

相关技能：capacitor-apple-review-preflight、capacitor-ci-cd、capgo-native-builds、capacitor-app-upgrades、capgo-live-updates。