Build prescan 체크 항목

이 플러그인의 설치 단계와 전체 markdown 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo Cloud Build가 프로젝트를 upload하기 전에, CLI가 실행되어 prescan 을 통해 credential, project, store-config 관련 문제를 로컬에서 미리 잡아냅니다.

단독 실행도 가능합니다:

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 숨기기 또는 건너뛰기 전체 나머지 체크 항목. 특정 규칙만 제외하려면 개별 체크 항목별 오버라이드를 사용하세요.

Check catalog 확인

다음에서 정확한 id를 사용하세요 --prescan-skip / --prescan-warn.

단계적 적용 해당 결과가 정보성(information-only)임을 의미하며, 다음 단계까지는 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 assets 빌드 및 Capacitor 플러그인 동기화 완료	—
`shared/node-linker-layout`	iOS, Android	node_modules 구조가 Capacitor native 경로와 호환됨	—
`shared/bundle-id-consistency`	iOS, Android	Capacitor appId가 native 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가 앱과 일치함	—
`ios/profile-type-vs-mode`	ios	Profile 유형이 app_store / ad_hoc 모드와 일치함	—
`ios/cert-profile-pairing`	ios	프로비저닝 프로파일에 인증서가 포함되어 있습니다	—
`ios/targets-covered`	ios	모든 iOS 타겟에 프로비저닝 프로파일이 있습니다	—
`ios/infoplist-sanity`	ios	Info.plist에 필수 버전/ID 키가 있습니다	—
`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	Launch screen이 선언되었습니다	예
`ios/plist-orientations-multitasking`	ios	Orientation / multitasking 설정이 일치합니다	예
`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+로 빌드 시 앱이 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	여러 앱 타겟은 의도된 동작입니다	예
`ios/entitlements-vs-profile-capability`	iOS	Entitlements가 프로필 권한과 일치합니다	예
`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	store 빌드 시 server.url이 live-reload 또는 remote 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	Exported 컴포넌트 보호	—
`android/manifest-query-all-packages`	android	QUERY_ALL_PACKAGES 소명 자료	—
`android/manifest-deeplink-valid`	android	Deeplink intent-filter가 유효해 보입니다	—
`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	Flavor가 있는 경우 Flavor dimension이 선언되어 있습니다	—
`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 서비스 계정이 앱에 접근할 수 있습니다 (remote)	—

예시: remote Next.js / server.url 셸

프로덕션 환경을 로드하는 네이티브 셸을 배포하는 것은 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 명령어 옵션.