构建预扫描检查

复制一个包含安装步骤和本插件的完整 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 键可以请求本机构建	—
`shared/app-exists`	iOS, Android	应用程序 Id 存在并且可见于 API 键	—
`shared/credentials-saved`	iOS, Android	需要保存的iOS/Android凭据保存在本地	—
`shared/cap-sync-stale`	iOS, Android	Web资源构建并且Capacitor插件同步	—
`shared/node-linker-layout`	iOS, Android	Capacitornode_modules布局与Capacitor本地路径兼容	—
`shared/bundle-id-consistency`	iOS, Android	CapacitorappId与native 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	分发配置文件的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	UI背景模式值看起来有效	是
`ios/xcode-deployment-target-capacitor`	iOS	iOS部署目标满足Capacitor要求	是
`ios/xcode-signing-team`	iOS	签名团队已设置	是
`ios/xcode-bundle-id-mismatch-across-configs`	iOS	bundle id在Xcode配置中一致	是
`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环境匹配发布模式	是
`ios/entitlements-associated-domains-format`	iOS	关联域名格式正确	是
`ios/entitlements-app-groups-format`	iOS	应用组格式正确	是
`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 不是 blanket 通配符	是
`ios/pods-not-installed`	iOS	当使用 Pods 时，CocoaPods 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	内容.json图标文件存在于磁盘	是
`ios/appicon-marketing-missing`	iOS	1024×1024营销图标存在	是
`ios/spm-deployment-target-consistency`	iOS	SPM部署目标一致	是

安卓

平台	它检查	逐步强制	安卓
`android/keystore-opens`	android	安卓签名证书未过期	—
`android/keystore-expiry`	android	安卓	—
`android/cordova-vars-present`	android	cordova.variables.gradle 在 cap 同步后存在	—
`android/gradle-props-heuristics`	android	gradle.properties 常见构建错误规则	—
`android/play-sa-json`	android	gradle.properties 中的常见构建错误规则	—
`android/flavor-exists`	android	当配置了 Play 服务帐户时，Play 服务帐户 JSON 文件存在	—
`android/agp8-package-attr`	android	请求的产品风味存在	—
`android/manifest-well-formed`	android	AGP 8+ 中，Manifest 中的 package= 属性已移除（不再需要）	—
`android/manifest-tag-typo`	android	常见的清单标签拼写错误	—
`android/manifest-namespace-uri`	android	context	—
`android/manifest-missing-prefix`	android	xmlns:android命名空间URI是正确的	—
`android/manifest-exported-missing`	android	Android属性使用android:前缀	—
`android/manifest-multiple-uses-sdk`	android	只允许使用一个sdk元素	—
`android/manifest-duplicate-component`	android	仅使用一个uses-__CAPGO_KEEP_0__元素	—
`android/manifest-unique-permission`	android	自定义权限是独特的	—
`android/manifest-hardcoded-debuggable`	android	在Capgo的构建过程中，	—
`android/manifest-mock-location`	android	debuggable=true不被发布	—
`android/manifest-exported-unprotected`	android	ACCESS_MOCK_LOCATION不被发布	—
`android/manifest-query-all-packages`	android	导出的组件是受保护的	—
`android/manifest-deeplink-valid`	android	QUERY_ALL_PACKAGES的理由	—
`android/applicationid-present`	android	applicationId 在 app/build.gradle 中声明	—
`android/capacitor-build-gradle-applied`	android	capacitor.build.gradle存在时应用	—
`android/gradle-wrapper-present`	android	__CAPGO_KEEP_0__.build.gradle 存在时应用	—
`android/flavor-dimensions`	android	Gradle 包装文件存在	—
`android/google-services-file`	android	产品维度声明时存在产品	—
`android/local-properties-committed`	android	google-services.json 存在时插件应用中存在,local.properties 不包含敏感信息	—
`android/sdk-floors`	android	min/compile/target SDK 层面看起来有效	—
`android/target-sdk-play`	android	context	—
`android/min-sdk-capacitor`	android	minSdk 满足 Capacitor 要求	—
`android/version-fields`	android	minSdk 满足 __CAPGO_KEEP_0__ 的要求	—
`android/play-sa-access`	android	versionCode / versionName 有值	—

Play 服务账户可以访问应用（远程）

标题：示例：远程 Next.js / server.url shell server.url 是支持的Capacitor模式。预扫描标志 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 构建参考全局构建请求/预扫描命令选项。