构建预扫描检查
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
在 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-separatednpx @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-permission | iOS, Android | API 密钥可以请求原生构建 | — |
shared/app-exists | iOS, Android | App ID 存在,且对 API 密钥可见 | — |
shared/credentials-saved | iOS, Android | 本地保存必要的 iOS/Android 凭据 | — |
shared/cap-sync-stale | iOS, Android | 已构建 Web 资源并同步 Capacitor 插件 | — |
shared/node-linker-layout | iOS, Android | node_modules 布局与 Capacitor 原生路径兼容 | — |
shared/bundle-id-consistency | iOS, Android | Capacitor appId 与原生 bundle id / applicationId 一致 | — |
| ID | 平台 | 检查内容 | 逐步强制执行 |
|---|---|---|---|
ios/p12-opens | iOS | iOS .p12 文件可使用提供的密码打开 | — |
ios/p12-expiry | iOS | iOS 签名证书未过期 | — |
ios/profile-expiry | iOS | 描述文件未过期 | — |
ios/profile-bundle-match | iOS | 描述文件的 Bundle ID 与应用匹配 | — |
ios/profile-type-vs-mode | iOS | 描述文件类型与 app_store / ad_hoc 模式匹配 | — |
ios/cert-profile-pairing | iOS | 证书已嵌入描述文件 | — |
ios/targets-covered | iOS | 所有 iOS 目标均包含描述文件 | — |
ios/infoplist-sanity | iOS | Info.plist 包含必需的版本/标识键 | — |
ios/asc-key-valid | iOS | App Store Connect API 密钥字段有效 | — |
ios/asc-key-access | iOS | ASC API 密钥可访问应用(远程) | — |
ios/plist-bundle-id-format | iOS | CFBundleIdentifier 格式有效 | 是 |
ios/plist-version-short-format | iOS | CFBundleShortVersionString 格式有效 | 是 |
ios/plist-version-build-format | iOS | CFBundleVersion 格式有效 | 是 |
ios/plist-encryption-compliance | iOS | 已声明 ITSAppUsesNonExemptEncryption | 是 |
ios/plist-ats-arbitrary-loads | iOS | 生产环境未启用 NSAllowsArbitraryLoads | 是 |
ios/plist-launch-storyboard | iOS | 已声明启动屏 | 是 |
ios/plist-orientations-multitasking | iOS | 屏幕方向 / 多任务设置一致 | 是 |
ios/plist-orientations-present | iOS | 已声明 UISupportedInterfaceOrientations | 是 |
ios/plist-display-name | iOS | 已设置显示名称 | 是 |
ios/plist-background-modes-sanity | iOS | UIBackgroundModes 值有效 | 是 |
ios/plist-scene-lifecycle-xcode27 | iOS | 使用 Xcode 27+ 构建时,应用采用 UIScene 生命周期(iOS 27 SDK 要求) | 是 |
ios/xcode-deployment-target-capacitor | iOS | iOS 部署目标满足 Capacitor 要求 | 是 |
ios/xcode-signing-team | iOS | 已设置签名团队 | 是 |
ios/xcode-bundle-id-mismatch-across-configs | iOS | Xcode 配置中的 Bundle ID 保持一致 | 是 |
ios/xcode-enable-bitcode-leftover | iOS | 已移除 ENABLE_BITCODE 残留 | 是 |
ios/xcode-swift-version-sanity | iOS | Swift 版本设置合理 | 是 |
ios/xcode-no-app-target | iOS | Xcode 项目包含应用目标 | 是 |
ios/xcode-multiple-app-targets | iOS | 多个 App Target 已按预期处理 | 是 |
ios/entitlements-vs-profile-capability | iOS | Entitlements 与描述文件能力匹配 | 是 |
ios/entitlements-aps-environment-vs-mode | iOS | aps-environment 与分发模式一致 | 是 |
ios/entitlements-associated-domains-format | iOS | Associated Domains 格式有效 | 是 |
ios/entitlements-app-groups-format | iOS | App Groups 格式有效 | 是 |
ios/capacitor-server-url-shipped | iOS | server.url 未保留为应用商店构建用的 live-reload / 远程 shell 端点 | 是 |
ios/capacitor-server-cleartext | iOS | 生产环境未启用 server.cleartext | 是 |
ios/capacitor-allow-navigation-wildcard | iOS | server.allowNavigation 不是全量通配符 | 是 |
ios/pods-not-installed | iOS | 使用 Pods 时,CocoaPods Pods / workspace 存在 | 是 |
ios/pods-lock-missing | iOS | Podfile.lock 固定了 pod 版本 | 是 |
ios/pods-capacitor-missing | iOS | Podfile 配置了 Capacitor | 是 |
ios/spm-package-resolved-missing | iOS | SPM Package.resolved 存在 | 是 |
ios/spm-capacitor-dependency-missing | iOS | Package.swift 声明了 Capacitor | 是 |
ios/appicon-empty-or-placeholder | iOS | AppIcon.appiconset 已存在且不为空 | 是 |
ios/appicon-referenced-file-missing | iOS | Contents.json 中的图标文件已存在于磁盘上 | 是 |
ios/appicon-marketing-missing | iOS | 1024×1024 营销图标已存在 | 是 |
ios/spm-deployment-target-consistency | iOS | SPM 部署目标一致 | 是 |
Android
标题为“Android”的章节| ID | 平台 | 检查内容 | 逐步强制执行 |
|---|---|---|---|
android/keystore-opens | Android | Android keystore 可使用提供的密码打开 | — |
android/keystore-expiry | Android | Android 签名证书未过期 | — |
android/cordova-vars-present | Android | cap sync 后存在 cordova.variables.gradle | — |
android/gradle-props-heuristics | Android | 针对常见构建失败的 gradle.properties 启发式检查 | — |
android/play-sa-json | Android | 配置后存在 Play service-account JSON | — |
android/flavor-exists | Android | 所请求的 product flavor 存在 | — |
android/agp8-package-attr | Android | AGP 8+ 中已移除 Manifest package= 属性 | — |
android/manifest-well-formed | Android | AndroidManifest.xml 解析通过 | — |
android/manifest-tag-typo | Android | 常见的 Manifest 标签拼写错误 | — |
android/manifest-namespace-uri | Android | xmlns:android 命名空间 URI 正确 | — |
android/manifest-missing-prefix | Android | Android 属性使用 android: 前缀 | — |
android/manifest-exported-missing | Android | 在需要处设置 android:exported | — |
android/manifest-multiple-uses-sdk | Android | 仅有一个 uses-sdk 元素 | — |
android/manifest-duplicate-component | Android | 无重复组件 | — |
android/manifest-unique-permission | Android | 自定义权限唯一 | — |
android/manifest-hardcoded-debuggable | Android | 未发布 debuggable=true | — |
android/manifest-mock-location | Android | 未发布 ACCESS_MOCK_LOCATION | — |
android/manifest-exported-unprotected | Android | 已导出组件受保护 | — |
android/manifest-query-all-packages | Android | QUERY_ALL_PACKAGES 理由 | — |
android/manifest-deeplink-valid | Android | Deeplink intent-filters 看起来有效 | — |
android/applicationid-present | Android | app/build.gradle 中已声明 applicationId | — |
android/capacitor-build-gradle-applied | Android | 应用时 capacitor.build.gradle 已存在 | — |
android/gradle-wrapper-present | Android | Gradle wrapper 文件已存在 | — |
android/flavor-dimensions | Android | 有 flavors 时已声明 Flavor dimensions | — |
android/google-services-file | Android | 应用插件时 google-services.json 已存在 | — |
android/local-properties-committed | Android | local.properties 未随敏感信息一起提交 | — |
android/sdk-floors | Android | min/compile/target SDK 最低版本看起来正常 | — |
android/target-sdk-play | Android | targetSdk 符合 Play Store 要求 | — |
android/min-sdk-capacitor | Android | minSdk 符合 Capacitor 要求 | — |
android/version-fields | Android | 已配置 versionCode / versionName | — |
android/play-sa-access | Android | Play 服务账号可访问该应用(远程) | — |
示例:远程 Next.js / server.url shell
标题为“示例:远程 Next.js / server.url shell”的章节发布一个加载生产环境的原生 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