문제 해결

설치

Capgo 빌드 문제 해결 방법

빌드 실패

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

Symptoms:

증상:
프로젝트 업로드 중 빌드가 실패

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 빌드하기 전에
네트워크 문제 확인
- 빌드 중에 일부 의존성은 큰 파일을 다운로드 할 수 있습니다
- 락 파일을 사용하여 미리 캐시하는 것을 고려하십시오

자연어 의존성을 검토하십시오

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

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

페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 보이는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).
- 지원 문의
- 특정 사용 사례에 맞게 한계치를 조정할 수 있습니다.

앱이 합법적으로 더 많은 시간이 필요하다면

“API 키가 유효하지 않다” 또는 “권한이 없습니다”

증상:

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

해결책:

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

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

API 권한 확인
- 권한이 있는지 확인하세요 write 키는 all 권한
- Capgo 대시보드의 API 키를 확인하세요.

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)

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

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

증상:

인증이 작동하지만 앱별 오류가 발생합니다.

Solutions:

앱이 등록되어 있는지 확인하세요
터미널 창
```
bunx @capgo/cli@latest app list
```
컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).
- Verify capacitor.config.json 확인
- 앱 ID
올바른 앱 ID를 사용하는지 확인하세요
- 앱 ID가 올바른지 확인하세요
- API 키는 앱의 조직에 접근할 수 있어야 합니다

iOS 빌드 문제

Code 서명 실패

증상:

code 서명 단계에서 빌드가 실패합니다.
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가 포함되어 있는지 확인하세요
- 인증서가 포함되어 있는지 확인하세요
인증서/프로파일을 삭제하고 새로 생성하세요
- 애플 개발자 포털에서 새로 생성하세요
- 환경 변수를 재인코딩하고 업데이트하세요
- 인증서가 포함되지 않은 프로비전 프로파일

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

증상:

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 포털에서 프로파일을 편집하세요.
- 다운로드 및 재 인코딩

애플 스토어 연결 인증 실패

증상:

테스트 플라이트 업로드 실패
API 키 오류

해결 방법:

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

API 키를 로컬 테스트하십시오

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

# Test with fastlane (if installed)
fastlane pilot list

API 권한 확인
- __CAPGO_KEEP_0__ 키 권한을 확인하십시오
- 키는 '개발자' 역할 이상이 필요합니다
App Store Connect -> 사용자 및 액세스 -> 키에서 확인하십시오
- 키가 취소되지 않았는지 확인하십시오
- App Store Connect에서 확인하십시오. 필요하다면 새로운 키를 생성하십시오

앱이 iOS 27에서 런칭 시 충돌합니다.

증상:

Xcode 27로 빌드한 iOS 27 앱은 TestFlight 또는 기기에서 즉시 종료됩니다.
에러 보고서가 다음과 같이 표시됩니다. _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

해결: apps built with the iOS 27 SDK must adopt the UIScene lifecycle. Add a SceneDelegate 그리고 하나 UIApplicationSceneManifest to ios/App/App/Info.plist‘Pod install failed’ 오류가 표시됩니다. --xcode-version 26Capgo이 현재 이러한 빌드를 시작하기 전에 차단합니다 (예측 검사) ios/plist-scene-lifecycle-xcode27).

apps built with the iOS 27 __CAPGO_KEEP_0__ must adopt the UIScene lifecycle. Add a ‘SceneDelegate’ class and implement the ‘application(_:configurationForConnecting connectingSceneSession:)’ method, and also implement the ‘application(_:didConnectScene session:)’ method, or build with ‘__CAPGO_KEEP_0__’ now blocks these builds before they start (prescan check ‘Pod install failed’

증상:

CocoaPods 설치 중 빌드 실패
Podfile 오류

해결 방법:

Podfile.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

안드로이드 빌드 문제

키스토어 비밀번호 오류

증상:

빌드가 서명 중에 실패합니다.
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

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

keystore의 올바른 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 업로드 실패’

증상:

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

해결책:

서비스 계정 JSON을 확인하세요

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

서비스 계정 권한을 확인하세요
- Play 콘솔로 이동 → 설정 → API 접근
- 서비스 계정에 앱에 대한 접근 권한이 있는지 확인하세요
- 테스트 트랙에 앱을 릴리스할 수 있는 권한을 부여하세요
앱이 Play 콘솔에 설정되어 있는지 확인하세요
- 앱은 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 제출을 위해
- 애플 스토어 연결 확인
- 업로드 후 처리가 5-30분 정도 소요될 수 있습니다.
Android Play Store를 위해
- 플레이 콘솔 → 테스트 → 내부 테스트 확인
- 처리가 몇 분 정도 소요될 수 있습니다.

빌드 성공했지만 환경switch 후에 artifact가 잘못되었다

증상:

빌드 상태는 success 그러나 IPA/AAB/APK은 branch 또는 flavor과 일치하지 않습니다.
Android AAB가 RC vs. production 인증서를 변경한 후에 누락되거나 잘못되었습니다. --android-flavor
빌드가 변경된 서명 구성 또는 제품 플래버 후에 수상하게 빠르게 완료되었습니다.

원인: Capgo은 기본적으로 앱당 빌드 캐시를 재생성합니다 (공유 일반 캐시를 위해 생략) cache_key RC와 프로덕션이 동일한 앱 ID를 공유하고 별도의 키를 사용하지 않는 경우, 재생성은 이전 환경에서 컴파일된 출력을 재사용할 수 있습니다.

해결책:

환경별 캐시 키 사용 (ongoing RC/PROD pipeline에 대해 권장)

# Production
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=prod \
  --android-flavor production

# Staging / RC
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=staging \
  --android-flavor staging

역할: UI 레이블. 위치: Capgo 마케팅 웹사이트. 본문 키 `agents_page_copy_label` (Agents Page Copy Label). 강제로 한 번의 정리된 빌드
터미널 창
```
bunx @capgo/cli@latest build request com.example.app --platform android --no-cache
```
API 또는 웹후크 통합, pass cache_key 예를 들어 "prod") 또는 설정 cache_enabled: false 단일 청소 실행을 위해

참조 빌드 캐시 CI/CD 관련 문제

CI/CD 관련 문제

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

Symptoms:

bunx @capgo/cli@latest … 해결책:

Solutions:

Bun 설정을 먼저 하세요 그렇습니다 bunx 사용 가능한 항목입니다:
```
- 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 }}

컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).
- 비밀 키 이름이 일치하는지 확인하세요.
- 이름은 대소문자를 구분합니다.

비밀 키 참조에 오류가 없는지 확인하세요.

제목: "더 많은 도움말을 받으려면"

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

context: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).

빌드 정보 수집 섹션

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

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에서 빌드하면 최적의 사용을 보장하기 위해 큐에 등록됩니다.
빌드 아티팩트 다운로드 가능성은 빌드 목적지와 아티팩트 저장 설정에 따라 달라집니다.

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

__CAPGO_KEEP_0__는 로컬

Capgo은 로컬 초기 스캔 업로드하기 전에. 발견된 문제를 수정하거나, 해당 체크 ID만 무시하세요:

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

페이지: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label). 전체 카탈로그 보기:.

Prescan 체크

추가 리소스 섹션 시작하기
- 초기 설정 가이드 - CLI 플래그 포함 --cache-key 및 --no-cache
iOS 빌드 - iOS 전용 설정
Android 빌드 - Android 전용 설정
빌드 전 검사 - 빌드 전 검사 및 무시 플래그 목록
CLI 참조 - 완전한 명령어 문서