构建预扫描检查

复制一个包含安装步骤和本插件的完整 Markdown 指南的配置提示。

在 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-permission`	iOS, Android	API key 可以请求本机构建	—
`shared/app-exists`	iOS, Android	API key 可见的 App ID 存在	—
`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	未过期的分发配置文件	—
`ios/profile-bundle-match`	iOS	签名配置文件的包ID与应用程序匹配	—
`ios/profile-type-vs-mode`	iOS	签名配置文件类型与应用程序的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/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	多个应用程序目标是故意处理的	是
`ios/entitlements-vs-profile-capability`	ios	特权匹配配置文件能力	是
`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	CocoaPods Pods / workspace 在使用 Pods 时存在	是
`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
`android/keystore-opens`	android	Android.keystore使用提供的密码打开	—
`android/keystore-expiry`	__CAPGO_KEEP_0__	Android	—
`android/cordova-vars-present`	Android签名证书未过期	android	—
`android/gradle-props-heuristics`	cordova.variables.gradle在cap同步后存在	android	—
`android/play-sa-json`	gradle.properties对常见构建错误的heuristics	android	—
`android/flavor-exists`	当配置时，Play服务帐户JSON存在	android	—
`android/agp8-package-attr`	请求的产品风味存在	Manifest package= 属性已移除（AGP 8+）	—
`android/manifest-well-formed`	Android	AndroidManifest.xml 解析	—
`android/manifest-tag-typo`	Android	常见的清单标签错误	—
`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`	安卓	deeplink意图过滤器看起来有效	—
`android/applicationid-present`	安卓	在app/build.gradle中声明了applicationId	—
`android/capacitor-build-gradle-applied`	安卓	capacitor.build.gradle存在时才会应用	—
`android/gradle-wrapper-present`	安卓	存在Gradle包装文件	—
`android/flavor-dimensions`	安卓	当存在flavor时才会声明flavor维度	—
`android/google-services-file`	安卓	Google 服务文件存在于插件应用时	—
`android/local-properties-committed`	Android	本地 properties 文件不包含敏感信息	—
`android/sdk-floors`	Android	最小/编译/目标 SDK 层面看起来有效	—
`android/target-sdk-play`	Android	目标 SDK 满足 Play Store 要求	—
`android/min-sdk-capacitor`	Android	最小 SDK 满足 Capacitor 要求	—
`android/version-fields`	Android	versionCode / versionName 都存在	—
`android/play-sa-access`	Android	Play 服务账户可以访问应用 (远程)	—

示例：远程 Next.js / server.url shell

将一个本地 shell 加载到生产环境中 server.url 这是一个支持的 Capacitor 模式。 Prescan flags 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。

故障排除上下文:支持/高级支持页面或底部支持部分。角色:部分或页面标题。见于:页面support-policy.astro。消息键`support_policy_troubleshooting_title` (支持政策故障排除标题)。

CLI build reference __CAPGO_KEEP_0__构建参考