문제 해결

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

Capgo 사용 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.

🚀 전문가의 도움이 필요하신가요?

복잡한 문제로 막혀 있나요? 전문가 팀이 도와드립니다! 맞춤형 지원과 code 리뷰, 그리고 필요에 꼭 맞는 커스텀 솔루션을 받아보세요.

전문 기술 지원 받기

업로드 실패

Bundle 업로드에 실패했다면 다음 사항을 확인하세요:

다음에 있는 App ID가 capacitor.config.ts Capgo dashboard의 앱과 일치하는지
Capacitor 프로젝트 루트에서 업로드 명령어를 실행 중인지
웹 에셋이 빌드되어 최신 상태인지

고급 업로드 옵션

Capgo CLI에서는 일반적인 업로드 문제 해결에 도움이 되는 추가 플래그를 제공합니다:

--tus: 다음을 사용합니다 tus resumable upload 프로토콜 대용량 bundle 또는 불안정한 네트워크 연결에서 더 안정적인 업로드를 위해. bundle이 10MB를 초과하거나 연결이 불안정하다면 다음을 사용하는 것을 고려하세요 --tus:
터미널 창
```
npx @capgo/cli@latest bundle upload --tus
```
--package-json 및 --node-modules: Capgo가 루트를 어디에서 찾을 수 있는지 알려줍니다 package.json 및 node_modules 모노레포나 npm 워크스페이스와 같은 비표준 구조를 사용하는 경우. 루트 경로를 전달하세요 package.json 및 --node_modules 경로:
터미널 창
```
npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules
```
Capgo가 앱의 의존성을 올바르게 번들링하려면 이 정보가 필요합니다.

이 플래그들은 다음과 같은 다른 옵션과 조합할 수 있습니다: --channel 필요에 따라 사용하세요. 참고: Capgo CLI 문서에서 사용 가능한 upload 옵션에 대한 자세한 내용을 확인하세요.

upload에 여전히 문제가 있다면, Capgo 지원팀에 공유해 주세요. 추가 지원을 받으려면 문의하세요.

업데이트 디버깅

Live Update 관련 문제가 발생하면 Capgo debug 명령어가 문제 해결에 유용합니다. 사용 방법은 다음과 같습니다:

프로젝트 디렉토리에서 다음 명령어를 실행하세요:
터미널 창
```
npx @capgo/cli@latest app debug
```
기기 또는 에뮬레이터에서 앱을 실행하고, 업데이트를 트리거해야 하는 동작을 수행하세요(예: 새 bundle 업로드 후 앱 재실행).
디버그 명령의 출력을 확인하세요. 업데이트 프로세스에 대한 다음 정보가 로그에 기록됩니다:
- 앱이 업데이트를 확인하는 시점
- 업데이트 발견 여부 및 해당 버전
- 업데이트 다운로드 및 설치 진행 상황
- 업데이트 프로세스 중 발생하는 모든 에러
디버그 로그를 사용해 문제가 발생하는 지점을 파악하세요. 예:
- 업데이트를 찾지 못했다면, bundle이 성공적으로 업로드되었는지, 앱이 올바른 channel을 사용하도록 설정되었는지 다시 확인하세요.
- 업데이트는 다운로드되지만 설치되지 않는다면, 다음 함수를 호출했는지 확인하세요: CapacitorUpdater.notifyAppReady() 그리고 앱이 완전히 종료된 뒤 다시 실행되었는지도 확인하세요.
- 에러 메시지가 표시되면 해당 에러를 Capgo 문서에서 찾아보거나 지원팀에 문의하세요.

debug 명령은 업데이트 다운로드 및 설치 과정의 문제를 파악하는 데 특히 유용합니다. 로그에 예상한 업데이트 버전이 발견되었지만 최종적으로 적용되지 않았다면, 다운로드 이후 단계에 트러블슈팅을 집중하세요.

Native Logs로 디버깅

Capgo debug 명령 외에도 Android, iOS, Electron의 native logs를 통해 업데이트 과정의 네이티브 측 문제를 해결하는 데 유용한 정보를 얻을 수 있습니다.

Android 로그

Android 로그를 확인하려면:

기기를 연결하거나 에뮬레이터를 실행하세요
Android Studio를 열고 “View > Tool Windows > Logcat”을 선택하세요
Logcat 창 상단의 드롭다운에서 해당 앱의 프로세스를 선택해 로그를 필터링하세요
다음 내용이 포함된 줄을 찾으세요 Capgo SDK 로그를 찾으려면

또는 adb logcat 명령 및 grep으로 검색 Capgo 로그를 필터링하세요.

Capgo SDK은 업데이트 과정에서 주요 이벤트를 기록합니다. 예:

업데이트 확인이 시작될 때
업데이트 발견 여부 및 해당 버전
업데이트 다운로드가 시작되고 완료될 때
업데이트 설치가 트리거될 때
네이티브 업데이트 단계에서 발생하는 모든 오류

로그에서 확인할 수 있는 일반적인 Android 관련 문제는 다음과 같습니다:

업데이트 다운로드를 방해하는 네트워크 연결 문제
업데이트 번들을 저장하거나 읽을 때 파일 권한 오류 발생
업데이트 번들 저장 공간 부족
업데이트 설치 후 앱 재시작 실패

iOS 로그

iOS 로그를 확인하려면:

기기를 연결하거나 시뮬레이터를 실행하세요
Xcode를 열고 “Window > Devices and Simulators”로 이동하세요
기기를 선택하고 “Open Console”을 클릭하세요
콘솔 출력에서 다음 내용이 포함된 줄을 찾으세요 Capgo SDK 로그를 찾으려면

또한 다음을 사용할 수도 있습니다: log stream 터미널에서 명령어를 실행하고 grep으로 Capgo 로그를 필터링하세요.

Android와 마찬가지로, Capgo SDK은 iOS 측의 주요 이벤트를 기록합니다:

업데이트 확인 시작 및 결과
다운로드 시작, 진행 상황 및 완료
설치 트리거 및 결과
native 업데이트 과정에서 발생하는 모든 에러

로그에서 확인할 수 있는 iOS 관련 이슈는 다음과 같습니다:

업데이트 다운로드 시 SSL 인증서 문제
App Transport Security로 인한 업데이트 다운로드 차단
업데이트 bundle에 필요한 저장 공간 부족
업데이트 bundle을 제대로 압축 해제하거나 적용하지 못함

Electron 로그

Electron 앱에서는 메인 프로세스와 렌더러 프로세스 출력을 모두 확인하세요:

평소 사용하는 실행 명령으로 터미널에서 Electron 앱을 실행하고 (예: bun run electron:dev 또는 bun run electron:serve) 터미널 출력에서 시작, 업데이트 확인, 네트워크 오류를 확인하세요.
렌더러 창에서 DevTools를 열고 (View → Toggle Developer Tools), 업데이트 흐름을 재현하면서 콘솔 로그와 실패한 네트워크 요청을 검사하세요.
패키징된 앱의 경우, OS 로그 도구에서 크래시나 시작 실패를 확인하세요:
- macOS가: 열기 Console.app 앱 이름으로 필터링하세요
- Windows: 열기 이벤트 뷰어 → Windows 로그 → 애플리케이션
- Linux: 데스크톱 로그 뷰어를 사용하거나 journalctl 앱 프로세스용

업데이트를 디버깅할 때는 main 프로세스와 renderer 프로세스 로그의 메시지를 비교해 Electron 부트스트랩 문제와 Capgo 업데이트 라이프사이클 문제를 구분하세요.

모든 플랫폼에서 native 로그는 업데이트 프로세스를 더 low-level 관점에서 볼 수 있게 해주며, native 구현에 대한 세부 정보도 더 많이 제공합니다. 특히 Capgo JavaScript 레이어 외부에서 발생하는 문제를 식별하는 데 유용합니다.

해결하기 까다로운 live update 문제를 트러블슈팅할 때는 전체적인 상황을 파악하려면 Capgo 디버그 로그와 native 로그를 모두 캡처하는 것이 좋습니다. 두 로그를 함께 보면 문제를 식별하고 해결하는 데 가장 도움이 됩니다.

업데이트가 적용되지 않음

번들을 업로드했는데 디바이스에서 변경 사항이 보이지 않는 경우:

앱에서 다음을 호출했는지 확인하세요: CapacitorUpdater.notifyAppReady() 다음과 같이 앱에서 code를 호출했는지 확인하세요: 빠른 시작
디바이스가 인터넷에 연결되어 있는지, 그리고 Capgo 디버그 로그에 업데이트가 다운로드되었는지 확인하세요
업데이트는 새로 시작할 때만 적용되므로 앱을 완전히 종료하고 다시 열어보세요
업데이트 적용 중 문제가 있음을 나타낼 수 있는 네이티브 로그의 오류를 확인하세요

다음 가이드를 참고하세요: Live Update 배포 업데이트 프로세스에 대한 자세한 내용은 가이드를 참고하세요. 여전히 막혀 있다면 다음을 사용하세요: npx @capgo/cli@latest app debug 명령어와 네이티브 로그를 확인하여 어떤 일이 일어나고 있는지 더 자세히 파악하세요.

자주 발생하는 업데이트 실패 코드

로그에 백엔드 오류가 표시되면 disable_auto_update_to_major, semver_error, 또는 cannot_update_via_private_channel, 전용 가이드를 사용하세요:

일반적인 업데이트 문제

각 code의 의미, 발생 원인, 해결 방법을 설명합니다.

SDK 설치

Capgo SDK 설치가 어려운 경우 다음을 확인하세요:

앱이 Capacitor의 지원 버전(4.0 이상)을 사용 중인지 확인하세요.
다음 단계를 순서대로 빠른 시작 진행했으며, SDK 설치 후 앱 동기화도 포함했습니다

CI/CD 통합

CI/CD 파이프라인에서 Capgo 업로드 트리거 관련 문제가 있는 경우:

Capgo 인증 토큰이 올바르게 설정되었는지 다시 확인하세요
웹 에셋 빌드 완료 후 업로드 명령을 실행하고 있는지 확인하세요
업로드 명령이 대상 환경에 맞는 올바른 채널 이름을 사용 중인지 확인하세요

참고하세요: 예제 앱의 CI/CD 통합 문서에서 추가 문제 해결 팁을 확인하세요. 또한 npx @capgo/cli@latest app debug 앱이 CI/CD 트리거된 업데이트를 수신하는지 확인하는 명령어입니다.

Troubleshooting에서 계속하기

사용 중이라면 문제 해결 저장 공간과 파일 처리를 계획하려면, 다음 항목과 연결하세요 @capgo/capacitor-data-storage-sqlite @capgo/capacitor-data-storage-sqlite의 구현 세부 사항은, @capgo/capacitor-data-storage-sqlite 사용하기 @capgo/capacitor-data-storage-sqlite 사용 시 네이티브 기능을 위해, @capgo/capacitor-file @capgo/capacitor-file의 구현 세부 사항은, @capgo/capacitor-file 사용하기 @capgo/capacitor-file 사용 시 네이티브 기능에 대해서는, 그리고 @capgo/capacitor-uploader @capgo/capacitor-uploader.의 구현 세부 사항에 대해서는