构建预扫描检查

在 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快速失败并显示明确的错误。

提示

需要 @capgo/cli@latest 支持每个检查的覆盖。尽量使用 --prescan-skip / --prescan-warn 这样其他每个检查仍然保护您的构建。

全局转义(尽量少用)

标志	效果
--no-prescan	跳过整个扫描
--prescan-ignore-fatal 或 --ignore-fatal 在 build prescan)	运行扫描，打印报告，不阻止
--fail-on-warnings	将警告视为致命（CI)

--no-prescan 并 --prescan-ignore-fatal 隐藏或绕过 所有 其余检查。使用每个检查的覆盖代替，当您只与一个规则不一致时。

检查目录

使用exact id --prescan-skip / --prescan-warn.

逐步强制 表示发现仅为信息性，直到 2026-08-14然后它可以阻止构建。

共享

ID	平台	它检查什么	逐步强制
shared/apikey-permission	iOS, Android	API key 可以请求本机构建	—
shared/app-exists	iOS, Android	App ID 存在且可见于 API key	—
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 App ID 与本机包 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 格式有效	Yes
ios/plist-version-short-format	iOS	CFBundleShortVersionString 格式有效	Yes
ios/plist-version-build-format	iOS	CFBundleVersion 格式有效	Yes
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	支持的界面方向是声明的	是
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	域名格式是有效的	是
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

ID	平台	它检查什么	逐步强制
android/keystore-opens	android	__CAPGO_KEEP_0__	—
android/keystore-expiry	Android.keystore	Android签名证书未过期	—
android/cordova-vars-present	Android	cap sync后cordova.variables.gradle存在	—
android/gradle-props-heuristics	Android	gradle.properties的常见构建问题	—
android/play-sa-json	Android	配置了Play服务帐号的JSON文件存在	—
android/flavor-exists	android	请求的产品风味存在	—
android/agp8-package-attr	android	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	安卓	当存在多个口味时才会声明口味维度	—
android/google-services-file	安卓	google-services.json存在于插件应用时	—
android/local-properties-committed	安卓	local.properties不包含敏感信息	—
android/sdk-floors	安卓	最小/编译/目标SDK楼层看起来有效	—
android/target-sdk-play	安卓	目标Sdk满足Play要求	—
android/min-sdk-capacitor	安卓	最小Sdk满足Capacitor要求	—
android/version-fields	安卓	versionCode/versionName存在	—
android/play-sa-access	安卓	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。

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

CLI build reference __CAPGO_KEEP_0__构建参考