跳转到正文

构建预扫描检查

在 Capgo Cloud Build 上传你的项目之前,CLI 会运行一次 预扫描 以便在本地发现凭据、项目和商店配置问题。

它也可以独立运行:

终端窗口
npx @capgo/cli@latest build prescan <appId> --platform ios

目前共有 80 项检查。建议忽略单个检查 ID,而不是关闭整个扫描。

终端窗口
# Skip one check entirely (example: intentional Capacitor server.url / Next.js shell)
npx @capgo/cli@latest build request <appId> --platform ios \
--prescan-skip ios/capacitor-server-url-shipped
# Run the check but never block on it (error becomes warning)
npx @capgo/cli@latest build request <appId> --platform ios \
--prescan-warn ios/capacitor-server-url-shipped
# Repeatable or comma-separated
npx @capgo/cli@latest build request <appId> --platform ios \
--prescan-skip ios/capacitor-server-url-shipped \
--prescan-warn ios/capacitor-allow-navigation-wildcard,ios/plist-ats-arbitrary-loads

独立别名已开启 build prescan:

终端窗口
npx @capgo/cli@latest build prescan <appId> --platform ios \
--skip ios/capacitor-server-url-shipped \
--warn ios/capacitor-server-cleartext

未知的检查 ID 会快速失败并返回清晰的错误信息。

参数效果
--no-prescan跳过整个扫描
--prescan-ignore-fatal (或 --ignore-fatal 开启 build prescan)运行扫描、打印报告,绝不阻塞
--fail-on-warnings将警告视为致命错误 (CI)

--no-prescan 以及 --prescan-ignore-fatal 隐藏或绕过 全部 剩余检查。如果只对某条规则有异议,请改用单项检查覆盖。

在……中使用确切的 id --prescan-skip / --prescan-warn.

逐步强制执行 意味着该发现项仅作信息提示,直到 2026-08-14,否则可能会阻止构建。

ID平台检查内容逐步强制执行
shared/apikey-permissioniOS, AndroidAPI 密钥可以请求原生构建—
shared/app-existsiOS, AndroidApp ID 存在,且对 API 密钥可见—
shared/credentials-savediOS, Android本地保存必要的 iOS/Android 凭据—
shared/cap-sync-staleiOS, Android已构建 Web 资源并同步 Capacitor 插件—
shared/node-linker-layoutiOS, Androidnode_modules 布局与 Capacitor 原生路径兼容—
shared/bundle-id-consistencyiOS, AndroidCapacitor appId 与原生 bundle id / applicationId 一致—
ID平台检查内容逐步强制执行
ios/p12-opensiOSiOS .p12 文件可使用提供的密码打开—
ios/p12-expiryiOSiOS 签名证书未过期—
ios/profile-expiryiOS描述文件未过期—
ios/profile-bundle-matchiOS描述文件的 Bundle ID 与应用匹配—
ios/profile-type-vs-modeiOS描述文件类型与 app_store / ad_hoc 模式匹配—
ios/cert-profile-pairingiOS证书已嵌入描述文件—
ios/targets-coverediOS所有 iOS 目标均包含描述文件—
ios/infoplist-sanityiOSInfo.plist 包含必需的版本/标识键—
ios/asc-key-validiOSApp Store Connect API 密钥字段有效—
ios/asc-key-accessiOSASC API 密钥可访问应用(远程)—
ios/plist-bundle-id-formatiOSCFBundleIdentifier 格式有效是
ios/plist-version-short-formatiOSCFBundleShortVersionString 格式有效是
ios/plist-version-build-formatiOSCFBundleVersion 格式有效是
ios/plist-encryption-complianceiOS已声明 ITSAppUsesNonExemptEncryption是
ios/plist-ats-arbitrary-loadsiOS生产环境未启用 NSAllowsArbitraryLoads是
ios/plist-launch-storyboardiOS已声明启动屏是
ios/plist-orientations-multitaskingiOS屏幕方向 / 多任务设置一致是
ios/plist-orientations-presentiOS已声明 UISupportedInterfaceOrientations是
ios/plist-display-nameiOS已设置显示名称是
ios/plist-background-modes-sanityiOSUIBackgroundModes 值有效是
ios/plist-scene-lifecycle-xcode27iOS使用 Xcode 27+ 构建时,应用采用 UIScene 生命周期(iOS 27 SDK 要求)是
ios/xcode-deployment-target-capacitoriOSiOS 部署目标满足 Capacitor 要求是
ios/xcode-signing-teamiOS已设置签名团队是
ios/xcode-bundle-id-mismatch-across-configsiOSXcode 配置中的 Bundle ID 保持一致是
ios/xcode-enable-bitcode-leftoveriOS已移除 ENABLE_BITCODE 残留是
ios/xcode-swift-version-sanityiOSSwift 版本设置合理是
ios/xcode-no-app-targetiOSXcode 项目包含应用目标是
ios/xcode-multiple-app-targetsiOS多个 App Target 已按预期处理是
ios/entitlements-vs-profile-capabilityiOSEntitlements 与描述文件能力匹配是
ios/entitlements-aps-environment-vs-modeiOSaps-environment 与分发模式一致是
ios/entitlements-associated-domains-formatiOSAssociated Domains 格式有效是
ios/entitlements-app-groups-formatiOSApp Groups 格式有效是
ios/capacitor-server-url-shippediOSserver.url 未保留为应用商店构建用的 live-reload / 远程 shell 端点是
ios/capacitor-server-cleartextiOS生产环境未启用 server.cleartext是
ios/capacitor-allow-navigation-wildcardiOSserver.allowNavigation 不是全量通配符是
ios/pods-not-installediOS使用 Pods 时,CocoaPods Pods / workspace 存在是
ios/pods-lock-missingiOSPodfile.lock 固定了 pod 版本是
ios/pods-capacitor-missingiOSPodfile 配置了 Capacitor是
ios/spm-package-resolved-missingiOSSPM Package.resolved 存在是
ios/spm-capacitor-dependency-missingiOSPackage.swift 声明了 Capacitor是
ios/appicon-empty-or-placeholderiOSAppIcon.appiconset 已存在且不为空是
ios/appicon-referenced-file-missingiOSContents.json 中的图标文件已存在于磁盘上是
ios/appicon-marketing-missingiOS1024×1024 营销图标已存在是
ios/spm-deployment-target-consistencyiOSSPM 部署目标一致是
ID平台检查内容逐步强制执行
android/keystore-opensAndroidAndroid keystore 可使用提供的密码打开—
android/keystore-expiryAndroidAndroid 签名证书未过期—
android/cordova-vars-presentAndroidcap sync 后存在 cordova.variables.gradle—
android/gradle-props-heuristicsAndroid针对常见构建失败的 gradle.properties 启发式检查—
android/play-sa-jsonAndroid配置后存在 Play service-account JSON—
android/flavor-existsAndroid所请求的 product flavor 存在—
android/agp8-package-attrAndroidAGP 8+ 中已移除 Manifest package= 属性—
android/manifest-well-formedAndroidAndroidManifest.xml 解析通过—
android/manifest-tag-typoAndroid常见的 Manifest 标签拼写错误—
android/manifest-namespace-uriAndroidxmlns:android 命名空间 URI 正确—
android/manifest-missing-prefixAndroidAndroid 属性使用 android: 前缀—
android/manifest-exported-missingAndroid在需要处设置 android:exported—
android/manifest-multiple-uses-sdkAndroid仅有一个 uses-sdk 元素—
android/manifest-duplicate-componentAndroid无重复组件—
android/manifest-unique-permissionAndroid自定义权限唯一—
android/manifest-hardcoded-debuggableAndroid未发布 debuggable=true—
android/manifest-mock-locationAndroid未发布 ACCESS_MOCK_LOCATION—
android/manifest-exported-unprotectedAndroid已导出组件受保护—
android/manifest-query-all-packagesAndroidQUERY_ALL_PACKAGES 理由—
android/manifest-deeplink-validAndroidDeeplink intent-filters 看起来有效—
android/applicationid-presentAndroidapp/build.gradle 中已声明 applicationId—
android/capacitor-build-gradle-appliedAndroid应用时 capacitor.build.gradle 已存在—
android/gradle-wrapper-presentAndroidGradle wrapper 文件已存在—
android/flavor-dimensionsAndroid有 flavors 时已声明 Flavor dimensions—
android/google-services-fileAndroid应用插件时 google-services.json 已存在—
android/local-properties-committedAndroidlocal.properties 未随敏感信息一起提交—
android/sdk-floorsAndroidmin/compile/target SDK 最低版本看起来正常—
android/target-sdk-playAndroidtargetSdk 符合 Play Store 要求—
android/min-sdk-capacitorAndroidminSdk 符合 Capacitor 要求—
android/version-fieldsAndroid已配置 versionCode / versionName—
android/play-sa-accessAndroidPlay 服务账号可访问该应用(远程)—

发布一个加载生产环境的原生 shell server.url 是一种受支持的 Capacitor 模式。Prescan 会标记 ios/capacitor-server-url-shipped 因为它通常是 live-reload 的残留。

确认它,但不要禁用其他检查:

终端窗口
npx @capgo/cli@latest build request <appId> --platform ios \
--prescan-skip ios/capacitor-server-url-shipped

或者将其保留为警告以保持可见性:

终端窗口
npx @capgo/cli@latest build request <appId> --platform ios \
--prescan-warn ios/capacitor-server-url-shipped