构建预扫描检查

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

在 Capgo Cloud Build 上传您的项目之前，CLI 会运行一次 预扫描 (prescan) 以便在本地检测凭据、项目及商店配置问题。

它也可以独立运行：

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-permission`	iOS, Android	API 密钥可以请求 Native Build	—
`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 一致	—

iOS

ID	平台	检查内容	逐步强制执行
`ios/p12-opens`	iOS	iOS .p12 文件密码正确	—
`ios/p12-expiry`	iOS	iOS 签名证书未过期	—
`ios/profile-expiry`	iOS	Provisioning profile 未过期	—
`ios/profile-bundle-match`	iOS	Provisioning profile 的 bundle id 与 App 匹配	—
`ios/profile-type-vs-mode`	iOS	Profile 类型与 app_store / ad_hoc 模式匹配	—
`ios/cert-profile-pairing`	iOS	证书已嵌入描述文件	—
`ios/targets-covered`	iOS	所有 iOS Target 均已配置描述文件	—
`ios/infoplist-sanity`	iOS	Info.plist 包含必要的版本/标识符键值	—
`ios/asc-key-valid`	iOS	App Store Connect API 关键字段校验通过	—
`ios/asc-key-access`	iOS	ASC API 密钥可远程访问 App	—
`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	已声明启动页 (Launch screen)	是
`ios/plist-orientations-multitasking`	iOS	屏幕方向 / 多任务设置一致	是
`ios/plist-orientations-present`	iOS	已声明 UISupportedInterfaceOrientations	是
`ios/plist-display-name`	iOS	已设置显示名称 (Display name)	是
`ios/plist-background-modes-sanity`	iOS	UIBackgroundModes 值看起来有效	是
`ios/plist-scene-lifecycle-xcode27`	iOS	使用 Xcode 27+ 构建时，App 会采用 UIScene 生命周期（iOS 27 SDK 的要求）	是
`ios/xcode-deployment-target-capacitor`	iOS	iOS 部署目标符合 Capacitor 要求	是
`ios/xcode-signing-team`	iOS	已设置 Signing team	是
`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 项目包含 Application Target	是
`ios/xcode-multiple-app-targets`	iOS	有意支持多个 App Target	是
`ios/entitlements-vs-profile-capability`	iOS	Entitlements 与 Profile 能力匹配	是
`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

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	仅使用了一个 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 服务账号可远程访问该 App	—

示例：远程 Next.js / server.url 壳程序

发布一个加载生产环境内容的 Native Build 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

快速入门创建您的第一个 Capgo Cloud Build。

故障排除常见的 Cloud Build 失败原因及解决方法。

CLI 构建参考完整的构建请求 / prescan 命令选项。