문제 해결

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함하여 설정 지침을 복사하세요.

Capgo Cloud Build를 사용하여 네이티브 앱을 빌드할 때 발생하는 일반적인 문제 해결 방법입니다.

빌드 실패

”Upload failed” or “Connection timeout”

증상:

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

솔루션:

인터넷 연결을 확인하세요

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

프로젝트 크기를 줄이기
- 확인하십시오 node_modules/ 업로드 중이 아닙니다 (자동으로 제외되어야 함)
- 프로젝트 내에 큰 파일이 있는지 확인:
터미널 창
```
find . -type f -size +10M
```
업로드 URL 만료 확인
- 업로드 URL은 1시간 후 만료됩니다
- 만료된 URL 오류가 발생하면 다시 빌드 명령어를 실행하세요.

10분 후 빌드 타임아웃

증상:

빌드 시간이 최대 허용 시간을 초과합니다.
상태 표시줄에서 timeout

해결 방법:

의존성 최적화
- 사용하지 않는 npm 패키지를 제거
- 사용하기 npm prune --production __CAPGO_KEEP_0__
네트워크 문제가 있는지 확인하기
- 빌드 중에 일부 의존성은 큰 파일을 다운로드 할 수 있습니다
- 특정 파일을 다운로드 받기 전에 캐시를 미리 설정하는 것을 고려해 보세요

자연어 의존성을 검토하세요

# iOS - check Podfile for heavy dependencies
cat ios/App/Podfile

# Android - check build.gradle
cat android/app/build.gradle

지원 요청하기
- 앱이 합법적으로 더 많은 시간이 필요하다면
- 특정 사용 사례에 대해 제한을 조정할 수 있습니다

인증 문제

API 키가 유효하지 않음

증상:

인증 오류로 인해 빌드가 즉시 실패합니다.
401 또는 403 오류

해결책:

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

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

API 키 권한을 확인하세요.
- 키는 write 또는 all 권한
- Capgo 대시보드의 API 키 아래에서 확인하세요

API 키가 읽히고 있는지 확인하세요

# Check environment variable
echo $CAPGO_TOKEN

# Or verify local .capgo file
cat .capgo

다시 인증
터미널 창
```
npx @capgo/cli@latest login
```

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

앱에 대한 권한이 없습니다

인증이 작동하지만 앱-특정 오류

해결책:

앱이 등록되어 있는지 확인하세요
터미널 창
```
npx @capgo/cli@latest app list
```
앱 ID가 일치하는지 확인하세요
- 확인 capacitor.config.json appId
- 올바른 앱 ID를 사용하는 명령어를 확인하세요
조직에 대한 액세스를 확인하세요
- 현재 올바른 조직에 있는지 확인하세요
- API 키는 앱의 조직에 접근할 수 있어야 합니다

iOS 빌드 문제

”Code signing failed”

증상:

Build fails during code signing phase
Xcode에서 인증서 또는 프로파일과 관련된 오류

해결 방법:

인증서 유형이 빌드 유형과 일치하는지 확인하십시오.
- 개발 빌드는 개발 인증서가 필요합니다.
- 앱 스토어 빌드는 배포 인증서가 필요합니다.

인증서 및 프로파일이 일치하는지 확인하십시오.

# 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

프로비저닝 프로파일이 유효한지 확인하세요
- 만료일을 확인하세요
- 앱 ID가 포함되어 있는지 확인하세요
- 인증서가 포함되어 있는지 확인하세요
인증서/프로파일을 재생성
- 구의 인증서/프로파일을 삭제
- Apple Developer Portal에서 새로운 인증서/프로파일을 생성
- 환경 변수를 재인코딩하고 업데이트

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

증상:

Xcode에서 프로파일에 인증서가 없다고 말합니다.

해결책:

최신 프로파일을 Apple에서 다운로드하세요.
- Apple Developer → 인증서, ID 및 프로파일로 이동하세요.
- 프로비전 프로파일 다운로드
- 인증서가 포함되어 있는지 확인하세요.

프로파일에 인증서가 있는지 확인하세요.

# Extract profile
echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision

# View profile contents
security cms -D -i profile.mobileprovision

인증서가 올바르게 포함된 프로파일을 다시 생성하세요.
- Apple Developer 포털에서 프로파일을 편집하세요.
- __CAPGO_KEEP_0__ 인증서를 선택하십시오.
- 다운로드 및 재 인코딩

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

증상:

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

해결책:

API 키 인증서를 확인하십시오.
- APPLE_KEY_ID (10 자리 문자열이어야 함)를 확인하십시오.
- APPLE_ISSUER_ID (UUID 형식이어야 함)를 확인하십시오.
- APPLE_KEY_CONTENT가 올바르게 base64 인코딩되어 있는지 확인하십시오.

테스트 API 키를 로컬에서

# Decode key
echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8

# Test with fastlane (if installed)
fastlane pilot list

API 키 권한 확인
- 키는 '개발자' 역할 이상이거나
- App Store Connect → 사용자 및 액세스 → 키 → 확인
키가 취소되지 않았는지 확인
- App Store Connect에서 확인
- 필요한 경우 새로운 키 생성

”Pod install failed”

증상:

CocoaPods 설치 중 오류가 발생합니다.
Podfile 오류

해결 방법:

Podfile.lock이 커밋되었는지 확인하세요.
터미널 창
```
git status ios/App/Podfile.lock
```
로컬에서 pod install 테스트
터미널 창
```
cd ios/App
pod install
```
비호환되는 pods가 있는지 확인하세요.
- Podfile에서 버전 충돌을 확인하세요.
- iOS 배포 대상이 지원되는 모든 pods가 있는지 확인하세요.

Cache pod을 초기화하세요

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

안드로이드 빌드 문제

”Keystore password incorrect”

증상:

인증 과정에서 빌드가 실패합니다
Gradle에서 키 스토어에 대한 오류가 발생합니다

해결 방법:

키 스토어 비밀번호를 확인하세요

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

환경 변수 확인

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

base64 인코딩 확인

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

”Key alias not found”

증상:

별칭 오류로 서명 실패

해결책:

키 저장소 별칭 목록

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

별칭이 정확히 일치하는지 확인
- 별칭은 대소문자를 구분합니다
- KEYSTORE_KEY_ALIAS에 오류가 있는지 확인

키 저장소에서 올바른 별칭을 사용하세요

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

'Gradle 빌드 실패'

증상:

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

해결책:

지역 테스트 빌드를 먼저 확인하세요
터미널 창
```
cd android
./gradlew clean
./gradlew assembleRelease
```
의존성 누락 여부 확인
- build.gradle 파일을 검토
- 모든 플러그인을 의존성 목록에 포함

Gradle 버전 호환성 확인

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

Gradle 캐시 지우기

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

”Play Store upload failed”

Symptoms:

Build succeeds but upload fails
Service account errors

Solutions:

Verify service account JSON

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

서비스 계정 권한 확인
- Play Console → 설정 → API 액세스 이동
- 서비스 계정에 앱에 대한 접근 권한이 있는지 확인
- Grant “Release to testing tracks” permission
앱이 Play Console에 설정되어 있는지 확인
- Play Console에서 앱을 먼저 생성해야 함
- 최소한 한 개의 APK를 수동으로 업로드해야 함
API이 활성화되어 있는지 확인
- Google Play Developer API이 활성화되어 있는지 확인
- Google Cloud Console에서 확인

일반적인 문제

”Job not found” or “Build status unavailable”

증상:

빌드 상태를 확인할 수 없습니다
빌드 ID 오류

해결책:

잠시 기다리십시오 다시 시도하십시오
- 빌드 작업이 몇 초 동안 초기화될 수 있습니다
빌드 ID가 정확한지 확인하십시오
- 초기 빌드 응답에서 빌드 ID를 확인하십시오
빌드가 만료되지 않았는지 확인하십시오
- 24시간 동안 데이터 빌드가 사용 가능합니다.

”Project sync failed”

증상:

빌드가 컴파일이 시작되기 전에 실패합니다.
파일 오류

해결책:

Capacitor를 로컬에서同步하세요.
터미널 창
```
npx cap sync
```
모든 네이티브 파일이 커밋되었는지 확인하세요.
터미널 창
```
git status ios/ android/
```
로컬 네이티브 파일이 gitignore 되지 않았는지 확인
- .gitignore 검토
- 중요한 설정 파일이 gitignore 되지 않았는지 확인

”Build succeeded but I don’t see output”

증상:

빌드가 성공했지만 다운로드 링크가 보이지 않습니다.

해결책:

빌드 설정을 확인하세요.
- 아티팩트 저장소가 구성되지 않았는지 확인하세요.
- 아티팩트 접근이 불가한 경우 지원팀에 문의하세요.
iOS 테스트 플라이트 제출을 위해
- 앱 스토어 연결 확인
- 업로드 후 5-30분 정도 소요될 수 있습니다.
안드로이드 플레이 스토어
- 플레이 콘솔 → 테스트 → 내부 테스트 확인
- 처리 시간이 몇 초 정도 소요될 수 있습니다.

CI/CD 관련 문제

GitHub 명령어를 찾을 수 없습니다.

증상:

npx @capgo/cli CI/CD에서 실패합니다.

솔루션:

Node.js가 설치되어 있는지 확인하세요

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

CLI을 명시적으로 설치하세요
```
- run: npm install -g @capgo/cli
```

GitHub Actions: “비밀번호가 발견되지 않음”

증상:

빌드 시 환경 변수가 빈 상태

솔루션:

비밀번호가 설정되어 있는지 확인하세요
- __CAPGO_KEEP_0__ Actions: “비밀번호가 발견되지 않음”로 이동하세요 → Settings → Secrets and variables → Actions
- 모든 필수적인 비밀번호를 추가하세요

정확한 문법을 사용하세요

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

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

더 많은 도움말을 받으려면

Verbose 로깅을 활성화하세요

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

빌드 정보 수집

지원에 문의할 때 포함하세요:

사용한 빌드 명령어

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

에러 메시지 (전체 출력)
작업 ID (빌드 출력에서)
빌드 로그 (전체 터미널 출력 복사)

환경 정보

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

지원 문의

디스코드: 우리 공동체에 가입하세요
이메일: capgo@capgo.app
문서: Capgo 문서

알려진 제한 사항

현재 제한 사항:

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

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

추가 리소스

시작하기 - 초기 설정 가이드
- iOS 빌드 - iOS-만족하는 설정
Android 빌드 - Android-만족하는 설정
CLI 참고문서 - 명령어 전체 문서