문제 해결

이 플러그인에 대한 설치 단계와 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.

Capgo Cloud Build와 함께 네이티브 앱을 빌드하는 데 발생하는 일반적인 문제의 해결책입니다.

빌드 실패

업로드 실패

증상:

업로드 프로젝트 시 빌드가 실패합니다.
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 패키지를 제거하세요.
- Use npm prune --production 빌드하기 전에 사용하세요.
네트워크 문제를 빌드 중에 확인하세요.
- 빌드 중에 일부 의존성이 큰 파일을 다운로드할 수 있습니다.
- 락 파일을 사용하여 미리 캐시하는 것을 고려하세요.

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

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

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

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

인증 오류

API 키가 유효하지 않거나

증상:

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

해결책:

API 키가 올바른지 확인하세요
__CAPGO_KEEP_0__ 터미널 창
```
# Test with a simple command
bunx @capgo/cli@latest app list
```
API 키 권한 확인
- __CAPGO_KEEP_0__ 키는 write 또는 all 권한
- Capgo API 대시보드에서 Capgo 키 확인

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)

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

앱이 존재하지 않거나 앱에 대한 권한이 없습니다.

증상:

인증이 성공적으로 완료되었지만 앱 관련 오류가 발생합니다.

해결 방법:

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

iOS 빌드 문제

“Code 인증서 서명 실패”

증상:

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

해결책:

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

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

# 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

프로비전 프로파일이 유효한지 확인하세요.
- 만료일을 확인하세요.
- __CAPGO_KEEP_2__ ID가 포함되어 있는지 확인하세요.
- 인증서가 포함되어 있는지 확인하세요.
__CAPGO_KEEP_3__을 재생성하세요.
- __CAPGO_KEEP_4__ 인증서/프로파일을 삭제
- Apple 개발자 포털에서 새로운 것을 생성하세요.
- 환경 변수를 재인코딩하고 업데이트하세요.

인증서가 포함되지 않은 프로비전 프로파일입니다.

증상:

프로파일에서 인증서를 찾을 수 없습니다.

해결책:

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

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

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

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

올바른 인증서로 프로필 다시 생성
- 애플 개발자 포털에서 프로필 편집
- 분배 인증서가 선택되어 있는지 확인
- 다운로드 및 재인코딩

”App Store Connect authentication failed”

App Store Connect 인증이 실패했습니다

증상:
API key errors

__CAPGO_KEEP_0__ 키 오류

API 인증 키를 확인하세요.
- APPLE_KEY_ID (10 자리여야 함)를 확인하세요.
- APPLE_ISSUER_ID (UUID 형식이어야 함)를 확인하세요.
- APPLE_KEY_CONTENT이 올바르게 base64 인코딩되어 있는지 확인하세요.
컴퓨터 시계를 동기화하세요.
- App Store Connect 인증은 로컬 시스템 시간으로부터 생성된 짧은 유효 기간의 JWT를 사용합니다.
- Apple은 20분 이상 유효 기간이 있는 토큰을 거부하므로, 시계가 약간 틀려도 유효한 키가 실패할 수 있습니다.
- Windows에서 열어보세요. 설정 > 시간 및 언어 > 날짜 및 시간 Sync now를 클릭하세요. macOS에서 열어보세요.
- __CAPGO_KEEP_0__ 시스템 설정 > 일반 > 날짜 및 시간 자동 시간 설정을 활성화하세요.
- Linux에서 확인하고 timedatectl status 필요한 경우 NTP를 활성화하세요.
- Capgo 빌드 또는 자격 증명 명령을 다시 실행하세요.
__CAPGO_KEEP_0__ 요청을 위한 토큰을 생성하는 방법 API App Store Connect 토큰 유효 기간 규칙에 대한 Apple의 문서를 참조하세요. __CAPGO_KEEP_0__ 키를 로컬에서 테스트하세요.

Test API key locally

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

# Test with fastlane (if installed)
fastlane pilot list

API 키 권한을 확인하세요.
- 개발자 역할 이상의 사용자가 필요합니다.
- 애플 스토어 연결 -> 사용자 및 액세스 -> 키 -> 확인
키가 취소되지 않았는지 확인하세요.
- 애플 스토어 연결 -> 확인
- 필요한 경우 새로운 키를 생성하세요.

”Pod install failed”

증상:

코코아팟 설치 중 빌드가 실패합니다.
팟파일 오류

해결책:

팟파일.lock이 커밋되었는지 확인하세요.
터미널 창
```
git status ios/App/Podfile.lock
```
로컬로 테스트용 pod 설치
터미널 창
```
cd ios/App
pod install
```
비호환되는 pod 확인
- Podfile의 버전 충돌을 검토
- iOS 배포 대상이 지원되는 모든 pod를 확인

pod 캐시를 삭제

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

Android 빌드 문제

”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

키 별칭이 없습니다

증상:

별칭 오류로 서명이 실패합니다

해결 방법:

키 스토어 별칭 목록

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

__CAPGO_KEEP_0__을 정확하게 확인하세요.
- __CAPGO_KEEP_0__은 대/소문자를 구분합니다.
- KEYSTORE_KEY_ALIAS에 오류가 있는지 확인하세요.

keystore의 정확한 __CAPGO_KEEP_0__을 사용하세요.

# 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

플레이 스토어 업로드 실패

증상:

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

해결 방법:

서비스 계정 JSON 확인

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

서비스 계정 권한 확인
- Play Console → 설정 → API 접근 설정
- 서비스 계정에 앱에 대한 접근 권한이 있는지 확인
- Grant “Release to testing tracks” 권한을 부여하십시오
앱이 Play Console에 설정되어 있는지 확인하십시오
- Play Console에 앱이 먼저 생성되어야 합니다
- 최소한 한 개의 APK가 수동으로 업로드되어야 합니다
API이 활성화되어 있는지 확인하십시오
- Google Play Developer API이 활성화되어 있어야 합니다
- Google Cloud Console에서 확인하십시오

일반적인 문제

작업이 존재하지 않거나 빌드 상태가 unavailable인 경우

증상:

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

해결 방법:

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

프로젝트 동기화 실패

증상:

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

해결책:

Capacitor을 로컬에서 동기화 하세요
터미널 창
```
bunx cap sync
```
모든 네이티브 파일이 커밋된 것을 확인하세요
터미널 창
```
git status ios/ android/
```
gitignored된 네이티브 파일을 확인하세요
- .gitignore을 검토하세요
- 중요한 구성 파일이 무시되지 않는지 확인하세요

성공했지만 출력을 볼 수 없어요

증상:

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

해결책:

빌드 설정을 확인하세요
- 아티팩트 저장소가 구성되지 않았을 수 있습니다
- 아티팩트 접근이 불가능한 경우 지원팀에 문의하세요
iOS TestFlight 제출을 위해
- App Store Connect를 확인하세요
- 업로드 후 5-30분 정도 처리가 소요될 수 있습니다
Android Play Store를 위해
- Check Play Console → Testing → Internal testing
- Processing may take a few minutes

CI/CD Specific Issues

GitHub Actions: “Command not found”

Symptoms:

bunx @capgo/cli@latest … CI에서 ‘command not found’로 실패합니다.

Solutions:

Bun을 먼저 설정하세요. 그럼 bunx is available:
```
- uses: oven-sh/setup-bun@v2
```
그런 다음 CLI을 실행하세요 — bunx __CAPGO_KEEP_0__은 필요할 때만 가져오므로 전역 설치가 필요하지 않습니다:
```
- run: bunx @capgo/cli@latest build request com.example.app --platform android
```

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

증상:

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

해결책:

비밀번호가 설정되어 있는지 확인하세요
- 레포지토리 설정 → 비밀번호 및 변수 → 액션으로 이동하여 모든 필요한 비밀번호를 추가하세요
- 레포지토리 설정 → 비밀번호 및 변수 → 액션

정확한 문법 사용

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

비밀 이름이 일치하는지 확인
- 이름은 대소문자 구별
- 비밀 참조에 오류가 없는지 확인

더 많은 도움말 얻기

Verbose 로깅 활성화

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

빌드 정보 수집

지원에 연락할 때 포함:

사용한 빌드 명령어

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

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

환경 정보

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

지원 문의

디스코드: 우리社区에 가입하세요
이메일: capgo.app의 지원
문서: Capgo 문서

알려진 제한 사항

현재 제한 사항:

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

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

추가 리소스

시작하기 - 초기 설정 가이드
iOS 빌드 - iOS 전용 구성
안드로이드 빌드 - 안드로이드 전용 설정
CLI Reference - 완전한 명령어 문서화