추가 리소스

Solutions to common issues when building native apps with Capgo Cloud Build.

빌드 실패

”Upload failed” or “Connection timeout”

증상:

• 프로젝트 업로드 중에 빌드가 실패합니다.
• 60초 후 시간 초과 오류

해결책:

1. 인터넷 연결을 확인하세요.

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. 프로젝트 크기를 줄이세요.

   • Ensure node_modules/ 업로드되지 않는다 (자동으로 제외되어야 함)
   • 프로젝트 내에 큰 파일이 있는지 확인하세요:

   find . -type f -size +10M

3. 업로드 URL 만료 확인

   • 업로드 URL은 1시간 후 만료됩니다.
   • 만료된 URL 오류가 발생하면 다시 빌드 명령어를 실행하세요.

팁

매우 큰 프로젝트는 빌드 시간 제한을 초과할 수 있습니다 (참조: 알려진 제한 사항기업 옵션을 원하신다면 지원팀에 문의하세요.

10분 이내에 빌드 시간 초과

증상:

• 빌드 시간이 최대 허용 시간을 초과합니다.
• 상태는 timeout

해결책:

1. 의존성 최적화

   • 사용하지 않는 npm 패키지를 제거
   • 빌드 전에 npm prune --production 네트워크 문제를 빌드 중에 확인

2. 빌드 중에 일부 의존성이 큰 파일을 다운로드할 수 있습니다.

   • Some dependencies may download large files during build
   • 해당 문제를 해결하기 위해

3. 자연적인 종속성을 검토하세요

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. 지원 문의

   • 컨텍스트: Capgo 마케팅 웹사이트. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 위치: 컴포넌트 가격/FAQ.Astro. 메시지 키 `contact_support` (지원 문의).
   • 앱이 합법적으로 더 많은 시간이 필요합니다

우리는 특정 사용 사례에 대한 제한을 조정할 수 있습니다

”API key invalid” or “Unauthorized”

__CAPGO_KEEP_0__ 키가 유효하지 않거나 인증되지 않은 섹션입니다. 또는 "Unauthorized"입니다. (권한이 없습니다.)

• 구축 오류가 즉시 인증 오류로 발생합니다.
• 401 또는 403 오류

해결책:

1. API 키가 올바른지 확인하세요.

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. API 키 권한을 확인하세요.

   • 키는 write 또는 all __CAPGO_KEEP_0__ 키의 권한을 확인하세요.
   • Check in Capgo dashboard under API Keys

3. API 키의 권한을 확인하세요.

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. 인증 재시도

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

증상:

• 인증이 성공했지만 앱 관련 오류

해결책:

1. 앱이 등록되어 있는지 확인

   bunx @capgo/cli@latest app list

2. 앱 ID가 일치하는지 확인하세요

   • 검증 capacitor.config.json appId
   • 올바른 앱 ID를 사용하는 명령어를 확인하세요

3. 조직 접근 권한을 검증하세요

   • 올바른 조직에 있는지 확인하세요
   • API 키는 앱의 조직에 접근할 수 있어야 합니다

iOS 빌드 문제

”Code signing failed”

증상:

• 빌드가 code 서명 단계에서 실패합니다.
• Xcode에서 인증서 또는 프로파일과 관련된 오류가 발생합니다.

해결책:

1. 인증서의 유형이 빌드 유형과 일치하는지 확인합니다.

   • 개발 빌드는 개발 인증서가 필요합니다.
   • 앱 스토어 빌드는 배포 인증서가 필요합니다.

2. 인증서와 프로파일이 일치하는지 확인합니다.

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. 프로비전 프로파일이 유효한지 확인합니다.

   • 만료일 확인
   • 인증 ID가 포함되어 있는지 확인하세요.
   • 인증서가 포함되어 있는지 확인하세요.

4. 인증서를 재생성하세요.

   • 기존 인증서/프로파일을 삭제하세요.
   • Apple Developer portal에서 새로운 인증서를 생성하세요.
   • 환경 변수를 재인코딩하고 업데이트하세요.

”Provisioning profile doesn’t include signing certificate”

Symptoms:

• Xcode can’t find certificate in profile

Solutions:

1. Download latest profile from Apple

   • Apple Developer → 인증서, ID 및 프로파일로 이동하세요.
   • 프로비저닝 프로파일 다운로드
   • 인증서가 포함되어 있는지 확인하세요.

2. 인증서가 프로파일에 포함되어 있는지 확인하세요.

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. 인증서가 올바른지 확인한 후 다시 프로파일을 생성하세요.

   • Apple Developer portal에서 프로파일 편집
   • 배포 인증서가 선택되어 있는지 확인하세요.
   • 다운로드하고 다시 인코딩하세요.

앱 스토어 연결 인증이 실패했습니다.

증상:

• 테스트 플라이트로 업로드가 실패합니다.
• API 키 오류

해결책:

1. API 키 인증서를 확인하세요.

   • APPLE_KEY_ID (10 자리 문자열이어야 함)를 확인하세요.
   • APPLE_ISSUER_ID (UUID 형식이어야 함)를 확인하세요.
   • APPLE_KEY_CONTENT가 올바르게 base64 인코딩되어 있는지 확인하세요.

2. 컴퓨터 시계를 동기화하세요.

   • 애플리케이션 스토어 연결 인증은 로컬 시스템 시간으로부터 생성된 짧은 유효 기간의 JWT를 사용합니다.
   • 애플은 20분 이상 유효 기간이 있는 토큰을 거부하므로, 심각한 시계 오차가 있는 경우 유효한 키가 실패할 수 있습니다.
   • Windows에서 열기 설정 > 시간 및 언어 > 날짜 및 시간 그리고 클릭 현재 동기화
   • macOS에서 열어 시스템 설정 > 일반 > 날짜 및 시간 자동 시간 동기화 활성화
   • Linux에서 확인 timedatectl status NTP 활성화가 필요하면
   • 동기화 후 Capgo 빌드 또는 자격 증명 명령 다시 실행

   애플의 API 요청을 위한 App Store Connect 토큰 유효 기간 규칙에 대한 문서를 참조하십시오. __CAPGO_KEEP_0__ 요청을 위한 App Store Connect 토큰 유효 기간 규칙에 대한 문서를 참조하십시오.

3. 테스트 API 키를 로컬에서

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. API 키 권한 확인

   • 키는 '개발자' 역할 이상이 필요합니다
   • 앱 스토어 커넥트 -> 사용자 및 액세스 -> 키 -> 확인

5. 키가 취소되지 않았는지 확인

   • 앱 스토어 커넥트 -> 확인
   • 필요한 경우 새로운 키를 생성

’Pod install failed’

증상:

• 설치 중 CocoaPods 오류
• Podfile 오류

해결 방법:

1. Podfile.lock이 커밋되었는지 확인하세요

   git status ios/App/Podfile.lock

2. 로컬에서 pod install 테스트하세요

   cd ios/App
   pod install

3. 비호환성 있는 pods가 있는지 확인하세요

   • Podfile에서 버전 충돌을 확인하세요
   • iOS 배포 대상이 지원되는지 모든 pods를 확인하세요

4. 캐시 삭제

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

안드로이드 빌드 문제

”Keystore password incorrect”

증상:

• 인증서로 인한 빌드 실패
• Gradle 에러: 인증서

해결책:

1. 인증서 비밀번호 확인

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. 환경 변수 확인

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. base64 인코딩 확인

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

키 별칭이 없습니다

증상:

• 인증에 실패한 별칭 오류

해결책:

1. 키 스토어 별칭 목록

   keytool -list -keystore my-release-key.keystore

2. 별칭이 정확히 일치하는지 확인

   • 별칭은 대소문자를 구분합니다
   • KEYSTORE_KEY_ALIAS에 오류가 있는지 확인

3. 키 스토어에서 올바른 별칭을 사용

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

”Gradle build failed”

증상:

• 일반적인 Gradle 오류
• 컴파일 또는 의존성 문제

해결책:

1. 지역에서 테스트 빌드 먼저 하세요

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 의존성 누락 여부 확인

   • build.gradle 파일 검토
   • 모든 플러그인 의존성 목록에 포함되어 있는지 확인

3. Gradle 버전 호환성 확인

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Gradle 캐시 지우기

   cd android
   ./gradlew clean
   rm -rf .gradle build

”Play Store upload failed”

증상:

• 빌드 성공하지만 업로드 실패
• 서비스 계정 오류

해결책:

1. 서비스 계정 JSON 확인

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. 서비스 계정 권한 확인

   • Play Console → 설정 → API 접근
   • 서비스 계정에 앱에 대한 접근 권한이 있는지 확인
   • ‘테스트 트랙으로 출시’ 권한 부여

3. 앱이 Play Console에 설정되어 있는지 확인

   • Play Console에서 앱이 먼저 생성되어야 함
   • 최소한 한 개의 APK가 수동으로 업로드되어야 함

4. API이 활성화되어 있는지 확인

   • Google Play Developer API이 활성화되어 있는지 확인
   • Google Cloud Console에서 확인

일반적인 문제

”Job not found” or “Build status unavailable”

증상:

• 빌드 상태 확인 불가
• Job ID 오류

해결책:

1. 잠시 기다리시오 다시 시도하십시오

   • 빌드 작업이 몇 초 동안 초기화될 수 있습니다

2. Job ID가 정확한지 확인하십시오

   • 초기 빌드 응답에서 Job ID를 확인하십시오

3. 빌드가 만료되지 않았는지 확인하십시오

   • 24시간 동안 빌드 데이터가 사용 가능합니다.

”Project sync failed”

Symptoms:

• Build fails before compilation starts
• Missing files errors

Solutions:

1. Run Capacitor sync locally

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. 로컬 네이티브 파일이 gitignore 되지 않았는지 확인하세요

   • .gitignore 파일을 검토하세요
   • 중요한 구성 파일이 gitignore 되지 않았는지 확인하세요

”Build succeeded but I don’t see output”

Symptoms:

• Build shows success but no download link

Solutions:

1. Check build configuration

   • Artifact storage may not be configured
   • Contact support if artifact access is unavailable for your build

2. For iOS TestFlight 제출

   • App Store Connect을 확인하세요
   • 업로드 후 5-30분 정도 소요될 수 있습니다

3. For Android Play Store

   • Play Console → Testing → 내부 테스트 → 확인하세요
   • 처리 시간이 몇 초 정도 소요될 수 있습니다

CI/CD 관련 문제

GitHub Actions: “명령어를 찾을 수 없습니다”

증상:

• bunx @capgo/cli@latest … CI에서 “명령어를 찾을 수 없습니다”라는 오류로 실패합니다

해결책:

1. Bun을 먼저 설정하세요 그래서 bunx 사용할 수 있습니다:

   - uses: oven-sh/setup-bun@v2

2. 그 다음 CLI을 실행하세요 — bunx 필요한 경우에만 __CAPGO_KEEP_0__이 자동으로 다운로드되며 전역 설치가 필요하지 않습니다:

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub 액션: “비밀번호가 없습니다”

증상:

• 빌드 시 환경 변수가 비어 있습니다

해결책:

1. 비밀 키가 설정되어 있는지 확인하세요

   • 저장소 설정 → Secret 및 변수 → Actions로 이동하세요
   • 필요한 모든 비밀 키를 추가하세요

2. 정확한 문법을 사용하세요

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. 비밀 키 이름이 일치하는지 확인하세요

   • 이름은 대소문자를 구분합니다
   • 비밀 키 참조에 오류가 없는지 확인하세요

더 많은 도움말을 받으려면

Verbose 로깅을 활성화하세요

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

빌드 정보 수집

지원 담당자에게 연락할 때 포함하세요:

1. 사용한 빌드 명령어

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. 에러 메시지 (전체 출력)

3. 작업 ID (from build output)

4. 빌드 로그 (터미널 출력 전체 복사)

5. 환경 정보

   node --version
   npm --version
   bunx @capgo/cli@latest --version

지원 문의

• 디스코드: 우리 커뮤니티에 가입하세요
• 이메일: support@capgo.app
• 문서: Capgo Docs

알려진 제한 사항

현재 제한 사항:

• 최대 빌드 시간: 10분
• 최대 업로드 크기: ~500MB
• iOS 빌드는 24시간 Mac 임대가 필요하며 Mac에서 빌드하면 최적의 사용을 위해 큐에 등록됩니다.
• 빌드 아티팩트 다운로드 가능성은 빌드 목적지와 아티팩트 저장소 구성에 따라 달라집니다.

이러한 제한 사항은 사용자 피드백에 따라 조정될 수 있습니다.

Prescan이 빌드를 차단했습니다

Capgo은 로컬 초기 스캔 업로드하기 전에 스캔합니다. 보고된 발견을 수정하거나, 다음 ID만 무시하세요:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

전체 카탈로그 보기 Prescan 검사.

추가 리소스

• 시작하기 - 초기 설정 가이드
• iOS 빌드 - iOS 전용 설정
• 안드로이드 빌드 - 안드로이드 전용 설정
• 프리 스캔 검사 - 빌드 전 전체 검사 및 무시 플래그 목록
• CLI 참조 - 완전한 명령어 문서