문제 해결

Capgo Cloud Build로 네이티브 앱을 빌드할 때 발생하는 일반적인 문제에 대한 해결 방법입니다.

빌드 실패

”업로드 실패” 또는 “연결 시간 초과”

증상:

• 프로젝트 업로드 중 빌드 실패
• 60초 후 시간 초과 오류

해결 방법:

1. 인터넷 연결 확인

   # Capgo에 대한 연결 테스트
   curl -I https://api.capgo.app

2. 프로젝트 크기 축소

   • node_modules/가 업로드되지 않는지 확인 (자동 제외되어야 함)
   • 프로젝트에서 대용량 파일 확인:

   find . -type f -size +10M

3. 업로드 URL 만료 확인

   • 업로드 URL은 1시간 후 만료됨
   • 만료된 URL 오류가 발생하면 빌드 명령을 다시 실행

팁

대용량 프로젝트(>200MB)는 시간 초과 제한에 도달할 수 있습니다. 엔터프라이즈 옵션은 지원팀에 문의하세요.

”10분 후 빌드 시간 초과”

증상:

• 빌드가 허용된 최대 시간 초과
• 상태가 timeout 표시

해결 방법:

1. 종속성 최적화

   • 사용하지 않는 npm 패키지 제거
   • 빌드 전 npm prune --production 사용

2. 빌드의 네트워크 문제 확인

   • 일부 종속성은 빌드 중 대용량 파일을 다운로드할 수 있음
   • 잠금 파일로 사전 캐싱 고려

3. 네이티브 종속성 검토

   # iOS - 무거운 종속성을 위해 Podfile 확인
   cat ios/App/Podfile
   
   # Android - build.gradle 확인
   cat android/app/build.gradle

4. 지원팀에 문의

   • 앱이 실제로 더 많은 시간이 필요한 경우
   • 특정 사용 사례에 대해 제한을 조정할 수 있음

인증 문제

”API 키 무효” 또는 “승인되지 않음”

증상:

• 인증 오류로 빌드가 즉시 실패
• 401 또는 403 오류

해결 방법:

1. API 키가 올바른지 확인

   # 간단한 명령으로 테스트
   npx @capgo/cli@latest app list

2. API 키 권한 확인

   • 키는 write 또는 all 권한을 가져야 함
   • Capgo 대시보드의 API 키에서 확인

3. API 키가 읽히는지 확인

   # 환경 변수 확인
   echo $CAPGO_TOKEN
   
   # 또는 로컬 .capgo 파일 확인
   cat .capgo

4. 재인증

   npx @capgo/cli@latest login

”앱을 찾을 수 없음” 또는 “이 앱에 대한 권한 없음”

증상:

• 인증은 작동하지만 앱별 오류

해결 방법:

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

   npx @capgo/cli@latest app list

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

   • capacitor.config.json appId 확인
   • 명령이 올바른 앱 ID를 사용하는지 확인

3. 조직 액세스 확인

   • 올바른 조직에 있는지 확인
   • API 키가 앱의 조직에 액세스 권한을 가져야 함

iOS 빌드 문제

”코드 서명 실패”

증상:

• 코드 서명 단계에서 빌드 실패
• 인증서 또는 프로파일에 대한 Xcode 오류

해결 방법:

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

   • Development 빌드에는 Development 인증서 필요
   • App Store 빌드에는 Distribution 인증서 필요

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

   # 인증서 디코딩 및 검사
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. 프로비저닝 프로파일이 유효한지 확인

   • 만료 날짜 확인
   • App ID 포함 여부 확인
   • 인증서 포함 여부 확인

4. 자격 증명 재생성

   • 이전 인증서/프로파일 삭제
   • Apple Developer 포털에서 새로 생성
   • 재인코딩 및 환경 변수 업데이트

”프로비저닝 프로파일에 서명 인증서가 포함되지 않음”

증상:

• Xcode가 프로파일에서 인증서를 찾을 수 없음

해결 방법:

1. Apple에서 최신 프로파일 다운로드

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

2. 인증서가 프로파일에 있는지 확인

   # 프로파일 추출
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # 프로파일 내용 보기
   security cms -D -i profile.mobileprovision

3. 올바른 인증서로 프로파일 재생성

   • Apple Developer 포털에서 프로파일 편집
   • distribution 인증서가 선택되었는지 확인
   • 다운로드 및 재인코딩

”App Store Connect 인증 실패”

증상:

• TestFlight 업로드 실패
• API 키 오류

해결 방법:

1. API 키 자격 증명 확인

   • APPLE_KEY_ID 확인 (10자여야 함)
   • APPLE_ISSUER_ID 확인 (UUID 형식이어야 함)
   • APPLE_KEY_CONTENT가 올바르게 base64 인코딩되었는지 확인

2. 로컬에서 API 키 테스트

   # 키 디코딩
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # fastlane으로 테스트 (설치된 경우)
   fastlane pilot list

3. API 키 권한 확인

   • 키에 “개발자” 역할 이상 필요
   • App Store Connect → 사용자 및 액세스 → 키에서 확인

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

   • App Store Connect에서 확인
   • 필요한 경우 새 키 생성

”Pod install 실패”

증상:

• CocoaPods 설치 중 빌드 실패
• Podfile 오류

해결 방법:

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

   git status ios/App/Podfile.lock

2. 로컬에서 pod install 테스트

   cd ios/App
   pod install

3. 호환되지 않는 pod 확인

   • Podfile에서 버전 충돌 검토
   • 모든 pod가 iOS 배포 대상을 지원하는지 확인

4. pod 캐시 지우기

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # 그런 다음 새 Podfile.lock 커밋

Android 빌드 문제

”키스토어 비밀번호 잘못됨”

증상:

• 서명 중 빌드 실패
• 키스토어에 대한 Gradle 오류

해결 방법:

1. 키스토어 비밀번호 확인

   # 로컬에서 키스토어 테스트
   keytool -list -keystore my-release-key.keystore
   # 프롬프트에서 비밀번호 입력

2. 환경 변수 확인

   # 추가 공백이나 특수 문자 확인
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. base64 인코딩 확인

   # 디코딩 및 테스트
   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. 키스토어의 올바른 별칭 사용

   # 환경 변수를 일치하도록 업데이트
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

”Gradle 빌드 실패”

증상:

• 일반적인 Gradle 오류
• 컴파일 또는 종속성 문제

해결 방법:

1. 먼저 로컬에서 빌드 테스트

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 누락된 종속성 확인

   • build.gradle 파일 검토
   • 모든 플러그인이 종속성에 나열되어 있는지 확인

3. Gradle 버전 호환성 확인

   # gradle 버전 확인
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Gradle 캐시 지우기

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

”Play Store 업로드 실패”

증상:

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

해결 방법:

1. 서비스 계정 JSON 확인

   # 디코딩 및 형식 확인
   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에서 확인

일반적인 문제

”작업을 찾을 수 없음” 또는 “빌드 상태를 사용할 수 없음”

증상:

• 빌드 상태를 확인할 수 없음
• 작업 ID 오류

해결 방법:

1. 잠시 기다린 후 재시도

   • 빌드 작업이 초기화하는 데 몇 초가 걸릴 수 있음

2. 작업 ID가 올바른지 확인

   • 초기 빌드 응답에서 작업 ID 확인

3. 빌드가 만료되지 않았는지 확인

   • 빌드 데이터는 24시간 동안 사용 가능

”프로젝트 동기화 실패”

증상:

• 컴파일이 시작되기 전에 빌드 실패
• 누락된 파일 오류

해결 방법:

1. 로컬에서 Capacitor 동기화 실행

   npx cap sync

2. 모든 네이티브 파일이 커밋되었는지 확인

   git status ios/ android/

3. gitignore된 네이티브 파일 확인

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

”빌드 성공했지만 출력이 보이지 않음”

증상:

• 빌드가 성공으로 표시되지만 다운로드 링크 없음

해결 방법:

1. 빌드 구성 확인

   • 아티팩트 저장소가 구성되지 않을 수 있음
   • 공개 베타의 경우 아티팩트 액세스에 대해 지원팀에 문의

2. iOS TestFlight 제출의 경우

   • App Store Connect 확인
   • 업로드 후 처리에 5-30분이 걸릴 수 있음

3. Android Play Store의 경우

   • Play Console → 테스트 → 내부 테스트 확인
   • 처리에 몇 분이 걸릴 수 있음

CI/CD 특정 문제

GitHub Actions: “명령을 찾을 수 없음”

증상:

• CI에서 npx @capgo/cli 실패

해결 방법:

1. Node.js가 설치되어 있는지 확인

   - uses: actions/setup-node@v6
     with:
       node-version: '24'

2. CLI를 명시적으로 설치

   - run: npm install -g @capgo/cli

GitHub Actions: “시크릿을 찾을 수 없음”

증상:

• 빌드에서 환경 변수가 비어 있음

해결 방법:

1. 시크릿이 설정되어 있는지 확인

   • 리포지토리 설정 → 시크릿 및 변수 → Actions로 이동
   • 모든 필수 시크릿 추가

2. 올바른 구문 사용

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

3. 시크릿 이름이 일치하는지 확인

   • 이름은 대소문자를 구분함
   • 시크릿 참조에 오타 없음

추가 도움 받기

자세한 로깅 활성화

# 디버그 플래그 추가 (사용 가능한 경우)
npx @capgo/cli@latest build com.example.app --verbose

빌드 정보 수집

지원팀에 문의할 때 다음을 포함하세요:

1. 사용된 빌드 명령

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

2. 오류 메시지 (전체 출력)

3. 작업 ID (빌드 출력에서)

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

5. 환경 정보

   node --version
   npm --version
   npx @capgo/cli --version

지원팀 문의

• Discord: 커뮤니티 참여
• 이메일: support@capgo.app
• 문서: Capgo 문서

알려진 제한 사항

공개 베타 동안의 현재 제한 사항:

• 최대 빌드 시간: 10분
• 최대 업로드 크기: ~500MB
• iOS 빌드에는 24시간 Mac 리스가 필요하며, Mac의 빌드는 최적의 사용을 보장하기 위해 대기열에 추가됩니다
• 빌드 아티팩트 다운로드를 사용할 수 없을 수 있음

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

추가 리소스

• 시작하기 - 초기 설정 가이드
• iOS 빌드 - iOS 전용 구성
• Android 빌드 - Android 전용 구성
• CLI 참조 - 전체 명령 문서