빌드 사전 검사
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
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-separatednpx @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-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 자산이 빌드되고 Capacitor 플러그인이 동기화됩니다 | — |
shared/node-linker-layout | iOS, Android | node_modules 구조가 Capacitor 네이티브 경로와 호환됩니다 | — |
shared/bundle-id-consistency | iOS, Android | Capacitor appId가 네이티브 bundle id / applicationId와 일치합니다 | — |
iOS
“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 | 런치 스크린이 선언되어 있음 | 지원 |
ios/plist-orientations-multitasking | iOS | 방향/멀티태스킹 설정이 일관됨 | 지원 |
ios/plist-orientations-present | iOS | UISupportedInterfaceOrientations가 선언되어 있음 | 지원 |
ios/plist-display-name | iOS | 표시 이름이 설정되었습니다 | 지원 |
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 프로젝트에 애플리케이션 타깃이 있습니다 | 지원 |
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 | 스토어 빌드에서 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
“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 | uses-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 | export된 컴포넌트 보호됨 | — |
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 요구사항을 충족합니다 | — |
android/min-sdk-capacitor | Android | minSdk가 Capacitor 요구사항을 충족합니다 | — |
android/version-fields | Android | versionCode / versionName이 존재합니다 | — |
android/play-sa-access | Android | Play 서비스 계정이 앱에 접근할 수 있음 (리모트) | — |
예: 원격 Next.js / server.url 셸
“예시: 리모트 Next.js / server.url 셸” 섹션프로덕션을 로드하는 네이티브 셸 배포 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관련 항목
“관련 항목” 섹션
시작하기
첫 번째 Capgo Cloud Build를 생성하세요.
문제 해결
Cloud Build의 일반적인 실패 사례와 해결 방법.
CLI 빌드 레퍼런스
빌드 요청 / prescan 명령 옵션 전체.