본문 바로가기

빌드 사전 검사

Capgo Cloud Build가 프로젝트를 업로드하기 전에, CLI가 실행되어 로컬 prescan을 로컬에서 인증 정보, 프로젝트, 스토어 설정 문제를 미리 찾아냅니다.

독립 실행도 가능합니다:

터미널 창
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

알 수 없는 check id는 명확한 에러와 함께 빠르게 실패합니다.

전역 이스케이프 (신중하게 사용)

“Global escapes (use sparingly)” 섹션
플래그효과
--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.

점진적 적용 해당 발견 항목은 정보 제공 목적이며, 다음 조건까지 2026-08-14, 그러면 빌드를 차단할 수 있습니다.

ID플랫폼검사 항목점진적 적용
shared/apikey-permissioniOS, AndroidAPI 키로 Native Build를 요청할 수 있음—
shared/app-existsiOS, AndroidApp ID가 존재하고 API 키에 표시됨—
shared/credentials-savediOS, Android필수 iOS/Android 자격 증명이 로컬에 저장됩니다—
shared/cap-sync-staleiOS, AndroidWeb 자산이 빌드되고 Capacitor 플러그인이 동기화됩니다—
shared/node-linker-layoutiOS, Androidnode_modules 구조가 Capacitor 네이티브 경로와 호환됩니다—
shared/bundle-id-consistencyiOS, AndroidCapacitor appId가 네이티브 bundle id / applicationId와 일치합니다—
ID플랫폼검사 항목점진적 적용
ios/p12-opensiOS제공된 비밀번호로 iOS .p12 파일이 열림—
ios/p12-expiryiOSiOS 서명 인증서가 만료되지 않음—
ios/profile-expiryiOSProvisioning profile이 만료되지 않음—
ios/profile-bundle-matchiOSProvisioning profile의 bundle id가 앱과 일치함—
ios/profile-type-vs-modeiOSProfile 유형이 app_store / ad_hoc 모드와 일치함—
ios/cert-profile-pairingiOS프로비저닝 프로파일에 인증서가 포함되어 있습니다—
ios/targets-coverediOS모든 iOS 타겟에 프로비저닝 프로파일이 있습니다—
ios/infoplist-sanityiOSInfo.plist에 필수 버전/ID 키가 있습니다—
ios/asc-key-validiOSApp Store Connect API 키 필드가 유효해 보입니다—
ios/asc-key-accessiOSASC API 키로 앱에 접근 가능합니다 (원격)—
ios/plist-bundle-id-formatiOSCFBundleIdentifier 형식이 유효합니다지원
ios/plist-version-short-formatiOSCFBundleShortVersionString 형식이 유효합니다지원
ios/plist-version-build-formatiOSCFBundleVersion 형식이 유효합니다지원
ios/plist-encryption-complianceiOSITSAppUsesNonExemptEncryption이 선언되어 있습니다지원
ios/plist-ats-arbitrary-loadsiOSNSAllowsArbitraryLoads가 프로덕션에서 활성화되지 않았습니다지원
ios/plist-launch-storyboardiOS런치 스크린이 선언되어 있음지원
ios/plist-orientations-multitaskingiOS방향/멀티태스킹 설정이 일관됨지원
ios/plist-orientations-presentiOSUISupportedInterfaceOrientations가 선언되어 있음지원
ios/plist-display-nameiOS표시 이름이 설정되었습니다지원
ios/plist-background-modes-sanityiOSUIBackgroundModes 값이 유효합니다지원
ios/plist-scene-lifecycle-xcode27iOSXcode 27+로 빌드할 때 앱이 UIScene 라이프사이클을 채택합니다 (iOS 27 SDK 요구 사항)지원
ios/xcode-deployment-target-capacitoriOSiOS 배포 대상이 Capacitor 요구 사항을 충족합니다지원
ios/xcode-signing-teamiOSSigning team이 설정되었습니다지원
ios/xcode-bundle-id-mismatch-across-configsiOSXcode 설정 간 Bundle ID 일관성 확인지원
ios/xcode-enable-bitcode-leftoveriOSENABLE_BITCODE 잔여 코드 제거 확인지원
ios/xcode-swift-version-sanityiOSSwift 버전 설정 적절성 확인지원
ios/xcode-no-app-targetiOSXcode 프로젝트에 애플리케이션 타깃이 있습니다지원
ios/xcode-multiple-app-targetsiOS여러 앱 타깃은 의도적으로 처리됩니다지원
ios/entitlements-vs-profile-capabilityiOSEntitlements가 프로필 기능과 일치합니다지원
ios/entitlements-aps-environment-vs-modeiOSaps-environment가 배포 모드와 일치합니다지원
ios/entitlements-associated-domains-formatiOSAssociated Domains 형식이 유효합니다지원
ios/entitlements-app-groups-formatiOSApp Groups 형식이 유효합니다지원
ios/capacitor-server-url-shippediOS스토어 빌드에서 server.url이 live-reload / remote shell 엔드포인트로 설정되지 않았습니다지원
ios/capacitor-server-cleartextiOS프로덕션에서 server.cleartext가 활성화되지 않았습니다지원
ios/capacitor-allow-navigation-wildcardiOSserver.allowNavigation은 무조건적 와일드카드가 아닙니다지원
ios/pods-not-installediOSPods 사용 시 CocoaPods Pods / workspace가 존재함지원
ios/pods-lock-missingiOSPodfile.lock에 pod 버전이 고정됨지원
ios/pods-capacitor-missingiOSPodfile에 Capacitor 연결됨지원
ios/spm-package-resolved-missingiOSSPM Package.resolved가 존재함지원
ios/spm-capacitor-dependency-missingiOSPackage.swift에 Capacitor 선언됨지원
ios/appicon-empty-or-placeholderiOSAppIcon.appiconset이 존재하고 비어 있지 않음지원
ios/appicon-referenced-file-missingiOSContents.json 아이콘 파일이 디스크에 존재함지원
ios/appicon-marketing-missingiOS1024×1024 마케팅 아이콘 존재함지원
ios/spm-deployment-target-consistencyiOSSPM 배포 대상이 일치합니다지원
ID플랫폼검사 항목점진적 적용
android/keystore-opensAndroid제공된 비밀번호로 Android keystore가 열립니다—
android/keystore-expiryAndroidAndroid 서명 인증서가 만료되지 않음—
android/cordova-vars-presentAndroidcap sync 후 cordova.variables.gradle 파일이 존재함—
android/gradle-props-heuristicsAndroid흔한 빌드 실패를 방지하는 gradle.properties 휴리스틱—
android/play-sa-jsonAndroid설정된 경우 Play service-account JSON이 존재함—
android/flavor-existsAndroid요청한 product flavor가 존재함—
android/agp8-package-attrAndroidAGP 8+용으로 Manifest package= 속성 제거됨—
android/manifest-well-formedAndroidAndroidManifest.xml 파싱됨—
android/manifest-tag-typoAndroid흔한 manifest 태그 오타—
android/manifest-namespace-uriAndroidxmlns:android 네임스페이스 URI가 올바름—
android/manifest-missing-prefixAndroidAndroid 속성에 android: 접두사 사용됨—
android/manifest-exported-missingAndroid필요한 곳에 android:exported 설정됨—
android/manifest-multiple-uses-sdkAndroiduses-sdk 요소는 하나만 사용됨—
android/manifest-duplicate-componentAndroid중복 컴포넌트 없음—
android/manifest-unique-permissionAndroid커스텀 권한은 고유함—
android/manifest-hardcoded-debuggableAndroiddebuggable=true 포함 안 됨—
android/manifest-mock-locationAndroidACCESS_MOCK_LOCATION 포함 안 됨—
android/manifest-exported-unprotectedAndroidexport된 컴포넌트 보호됨—
android/manifest-query-all-packagesAndroidQUERY_ALL_PACKAGES 사용 근거—
android/manifest-deeplink-validAndroidDeeplink intent-filter가 유효해 보입니다—
android/applicationid-presentAndroidapp/build.gradle에 applicationId가 선언되어 있습니다—
android/capacitor-build-gradle-appliedAndroid적용 시 capacitor.build.gradle 파일이 존재합니다—
android/gradle-wrapper-presentAndroidGradle wrapper 파일이 존재합니다—
android/flavor-dimensionsAndroidFlavor가 있는 경우 Flavor dimension이 선언되어 있습니다—
android/google-services-fileAndroid플러그인 적용 시 google-services.json 파일이 존재합니다—
android/local-properties-committedAndroidlocal.properties에 시크릿이 커밋되지 않았습니다—
android/sdk-floorsAndroidmin/compile/target SDK 하한값이 유효합니다—
android/target-sdk-playAndroidtargetSdk가 Play 요구사항을 충족합니다—
android/min-sdk-capacitorAndroidminSdk가 Capacitor 요구사항을 충족합니다—
android/version-fieldsAndroidversionCode / versionName이 존재합니다—
android/play-sa-accessAndroidPlay 서비스 계정이 앱에 접근할 수 있음 (리모트)—

프로덕션을 로드하는 네이티브 셸 배포 server.url 은(는) 지원되는 Capacitor 패턴입니다. Prescan은 플래그를 표시합니다 ios/capacitor-server-url-shipped 이는 종종 라이브 리로드 잔재이기 때문입니다.

다른 체크를 비활성화하지 않고 확인하세요:

터미널 창
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