构建预扫描检查

复制一个包含安装步骤和本插件的完整 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	配置文件类型与应用商店/广告模式匹配	—
`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	支持的界面方向是声明的	是
`ios/plist-display-name`	ios	显示名称已设置	是
`ios/plist-background-modes-sanity`	ios	UI后台模式值看起来是有效的	是
`ios/xcode-deployment-target-capacitor`	ios	Capacitor 的 iOS 部署目标满足要求	是
`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	__CAPGO_KEEP_0__项目有一个应用程序目标	是
`ios/xcode-multiple-app-targets`	ios	__CAPGO_KEEP_0__项目有多个应用程序目标是有意为之	是
`ios/entitlements-vs-profile-capability`	ios	__CAPGO_KEEP_0__项目的特权与配置文件能力匹配	是
`ios/entitlements-aps-environment-vs-mode`	ios	__CAPGO_KEEP_0__aps环境与发布模式匹配	是
`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
`android/keystore-opens`	android	Android.keystore使用提供的密码打开	—
`android/keystore-expiry`	__CAPGO_KEEP_0__	Android签名证书未过期	—
`android/cordova-vars-present`	__CAPGO_KEEP_0__	cordova.variables.gradle存在于cap同步后	—
`android/gradle-props-heuristics`	__CAPGO_KEEP_0__	Gradle属性的常见构建问题	—
`android/play-sa-json`	__CAPGO_KEEP_0__	Play服务帐户JSON存在于配置时	—
`android/flavor-exists`	__CAPGO_KEEP_0__	请求的产品风味存在	—
`android/agp8-package-attr`	__CAPGO_KEEP_0__	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`	安卓	深度链接意图过滤器看起来有效	—
`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 服务文件存在于插件应用时	—
`android/local-properties-committed`	Android	本地 properties 文件不包含敏感信息	—
`android/sdk-floors`	Android	SDK 最小/编译/目标楼层看起来有效	—
`android/target-sdk-play`	Android	目标 SDK 满足 Play 要求	—
`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 云构建。

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

CLI build reference __CAPGO_KEEP_0__ 构建参考