트러블 슈팅

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

Capgo를 사용하는 동안 발생할 수 있는 일반적인 문제와 해결 방법을 알려드립니다.

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

복잡한 문제로 막혔나요? 전문가 팀이 도와드리겠습니다! 개인화된 지원, code 리뷰, 및 고객맞춤 솔루션을 제공합니다.

전문 지원 받기

업로드 실패

bundle 업로드가 실패하면, 확인하세요:

앱 ID가 __CAPGO_KEEP_0__ 대시보드의 앱과 일치하는지 capacitor.config.ts matches your app in the Capgo dashboard
You’re running the upload command from the root of your Capacitor project
고급 업로드 옵션

고급 업로드 옵션 섹션

The Capgo CLI provides some additional flags to help with common upload issues:

--tus업로드 실패 시 확인해야 할 사항 __CAPGO_KEEP_0__ 대용량 패키지 또는 느린 네트워크 연결에서 더 신뢰할 수 있는 업로드를 위해 tus 재사용 가능한 업로드 프로토콜을 사용하세요. 패키지가 10MB를 초과하거나 네트워크 연결이 불안정한 경우, 대용량 패키지 업로드를 위해 --tus:
터미널 창
```
npx @capgo/cli@latest bundle upload --tus
```
--package-json : --node-modulesCapgo에서 루트 폴더 위치를 찾는 데 사용하세요. 앱이 모노레포 또는 Capgo 워크스페이스와 같은 비표준 구조를 사용하는 경우 루트 폴더 경로를 전달하세요. package.json 루트 폴더 경로: node_modules if your app uses a non-standard structure like a monorepo or npm workspace. Pass the path to the root package.json 클립보드 복사 --node_modules 루트 폴더 경로를 __CAPGO_KEEP_0__에 전달하세요.
루트 폴더 경로: __CAPGO_KEEP_0__
```
npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules
```
Capgo의 정보가 정확히 앱의 의존성을 패키징하기 위해 필요합니다.

__CAPGO_KEEP_0__의 플래그를 다른 옵션과 combination할 수 있습니다. --channel 필요한 대로. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__의 문서를 참조하여 업로드 옵션에 대한 자세한 정보를 확인하세요. Capgo CLI docs Debugging Updates

Debugging Updates Capgo의 디버그 명령어는 업데이트 중 문제가 발생하는 경우 문제 해결을 도와주는 도구입니다. 사용 방법은 다음과 같습니다. __CAPGO_KEEP_0__ 디렉토리에서 다음 명령어를 실행하세요:

__CAPGO_KEEP_0__

Capgo

프로젝트 디렉토리
Terminal 창
```
npx @capgo/cli@latest app debug
```
앱을 기기나 에뮬레이터에서 실행하고 업데이트를 트리거하는 액션(예: 새로운 번들을 업로드 한 후 앱을 다시 열기)을 수행하세요.
디버그 명령어의 출력을 관찰하세요. 업데이트 프로세스에 대한 정보를 포함하여 다음과 같은 로그를 출력합니다.
- 앱이 업데이트를 확인할 때
- 업데이트가 발견되었는지 여부와 버전
- 업데이트 다운로드 및 설치 진행 상황
- 업데이트 프로세스 중 발생하는 오류
디버그 로그를 사용하여 문제가 발생하는 위치를 식별하세요. 예를 들어:
- 업데이트가 발견되지 않으면, 번들이 성공적으로 업로드되었는지 확인하고 앱이 올바른 채널을 사용하도록 구성되었는지 확인하세요.
- 업데이트가 다운로드되지만 설치되지 않으면, __CAPGO_KEEP_0__를 호출했는지 확인하고 앱이 완전히 닫혔는지 여부와 앱을 다시 열었는지 확인하세요. CapacitorUpdater.notifyAppReady() __CAPGO_KEEP_0__
- Capgo 에러 메시지가 나타나면, 해당 에러를 Capgo 문서에서 찾아보거나 지원팀에 문의하여 도움을 받으세요.

업데이트 다운로드 및 설치 과정을 해결하기 위한 문제를 식별하는 데 특히 유용한 디버그 명령어입니다. 로그가 기대되는 업데이트 버전이 발견되었지만 최종적으로 적용되지 않았다면, 다운로드 이후의 단계에 집중하여 문제를 해결하세요.

자연어 로그 디버깅

Capgo 디버그 명령어 이외에도 Android, iOS, Electron에서 제공하는 자연어 로그는 업데이트 프로세스의 네이티브 측에서 발생하는 문제를 해결하는 데 유용한 정보를 제공합니다.

Android 로그

Android 로그에 접근하려면

장치에 연결하거나 에뮬레이터를 시작하세요
Android Studio를 열고 “보기 > 도구 창 > 로그캣”을 선택하세요
로그캣 창에서 로그를 필터링하여 앱의 프로세스만 선택하세요
__CAPGO_KEEP_0__ 에러 메시지가 나타나면, 해당 에러를 __CAPGO_KEEP_0__ 문서에서 찾아보거나 지원팀에 문의하여 도움을 받으세요. Capgo to find the SDK logs

대안으로는 adb logcat 명령어를 사용하고 grep으로 로그를 필터링할 수 있습니다. Capgo 로그를 필터링하기 위해 사용할 수 있습니다.

The Capgo SDK will log key events during the update process, such as:

업데이트 체크가 시작될 때
업데이트가 발견되었으며 어떤 버전인지
업데이트 다운로드가 시작되고 완료되었을 때
업데이트 설치가 트리거되었을 때
네이티브 업데이트 단계에서 발생하는 오류

로그에서 일반적으로 Android에서 볼 수 있는 문제로는:

네트워크 연결 문제로 업데이트 다운로드가 방해받는 경우
파일 권한 오류가 업데이트 배포본을 저장하거나 읽을 때 발생합니다.
업데이트 배포본을 저장할 수 있는 저장 공간이 없습니다.
업데이트가 설치된 후 앱을 다시 시작할 수 없습니다.

iOS 로그

iOS 로그에 접근하려면:

디바이스를 연결하거나 시뮬레이터를 시작하세요.
Xcode를 열고 “Window > Devices and Simulators”를 클릭하세요.
디바이스를 선택하고 “Open Console”을 클릭하세요.
콘솔 출력에서 __CAPGO_KEEP_0__ 로그를 포함하는 줄을 찾으세요. Capgo SDK 로그를 찾으려면

__CAPGO_KEEP_0__ 로그를 찾으려면 __CAPGO_KEEP_0__ 로그를 찾으세요. log stream 터미널에서 명령어를 입력하고 grep을 사용하여 Capgo 로그를 필터링합니다.

Android와 유사하게, Capgo SDK은 iOS 측 이벤트를 로깅합니다:

업데이트 체크 시작 및 결과
다운로드 시작, 진행, 완료
설치 트리거 및 결과
네이티브 업데이트 프로세스 중 오류

로그에서 식별할 수 있는 iOS 전용 문제는 다음과 같습니다:

다운로드 중 SSL 인증서 문제
업데이트 다운로드를 차단하는 앱 전송 보안
업데이트 패키지에 대한 충분한 저장 공간 부족
업데이트 패키지를 올바르게 추출하거나 적용하지 못하는 경우

Electron 로그

Electron 앱의 경우 메인 프로세스와 렌더러 프로세스 출력을 모두 확인하십시오.

터미널에서 Electron 앱을 실행하여 일반적인 런치 명령어를 사용하십시오 (예를 들어 bun run electron:dev 또는 bun run electron:serve) 그리고 시작, 업데이트 확인, 네트워크 오류와 같은 터미널 출력을 감시하십시오.
렌더러 창에서 개발자 도구를 열고 (View → Toggle Developer Tools) 업데이트 흐름을 재현하는 동안 콘솔 로그와 실패한 네트워크 요청을 검사하십시오.
패키지된 앱의 경우 OS 로그 도구를 사용하여 충돌이나 시작 오류를 확인하십시오:
- macOS: open Console.app 앱 이름으로 필터링하십시오.
- Windows: 열기 이벤트 뷰어 → 윈도우 로그 → 응용 프로그램
- 리눅스: 데스크톱 로그 뷰어를 사용하거나 journalctl 앱 프로세스

업데이트 중 디버깅할 때, 메인 프로세스와 렌더러 프로세스 로그에서 메시지를 비교하여 Electron 부트스트랩 문제와 Capgo 업데이트 라이프 사이클 문제를 분리하세요.

플랫폼 간에 네이티브 로그는 업데이트 프로세스에 대한 더 낮은 수준의 시각화를 제공하며, 네이티브 구현에 대한 더 많은 세부 정보를 제공합니다. 특히 Capgo 자바스크립트层 외부에서 발생하는 문제를 식별하는 데 유용합니다.

트러블 슈팅 중에 어려운 라이브 업데이트 문제를 해결할 때, Capgo 디버그 로그와 네이티브 로그를 모두 캡처하는 것이 좋습니다. 두 로그를 함께 사용하면 문제를 식별하고 해결하는 데 최선의 기회를 제공합니다.

업데이트가 적용되지 않음

If you’ve uploaded a bundle but aren’t seeing the changes on your device:

__CAPGO_KEEP_0__을 호출했는지 확인하세요. CapacitorUpdater.notifyAppReady() in your app code as shown in the quickstart
네트워크가 연결되어 있는지 확인하고 Capgo debug 로그에서 업데이트가 다운로드 된 것을 확인하세요.
앱을 완전히 종료하고 다시 열어보세요. 업데이트는 새로고침 시에만 적용됩니다.
업데이트 적용 중 오류가 있는지 native 로그를 확인하세요.

업데이트 프로세스에 대한 자세한 내용은 deploying live updates guide를 참조하세요. 여전히 막혔으면 npx @capgo/cli@latest app debug command와 native 로그를 사용하여 더 자세한 정보를 얻으세요.

업데이트 실패 코드

로그에 표시되는 백엔드 오류, 예를 들어 disable_auto_update_to_major, semver_error, 또는 cannot_update_via_private_channel,를 사용하는 경우

공통 업데이트 문제

이 문서는 각 공통 code의 의미, 발생 이유 및 해결 방법을 설명합니다.

SDK 설치

If you’re having trouble installing the Capgo SDK, make sure:

Capacitor의
빠른 시작 안내를 따라주세요. 설치 후 앱을同步하는 단계를 포함하여 SDK

CI/CD 통합

CI/CD pipeline에서 Capgo 업로드를 트리거하는 문제가 있는 경우:

Capgo 인증 토큰이 올바르게 설정되어 있는지 확인하세요
웹 자산이 빌드된 후 업로드 명령을 실행하는 것을 확인하세요
업로드 명령이 대상 환경의 올바른 채널 이름을 사용하는지 확인하세요

CI/CD 통합 더 많은 문제 해결 팁을 찾으려면 CI/CD 통합 문서를 참조하세요. 또한 CI/CD 트리거된 업데이트가 앱에 수신되는지 확인하려면 명령을 사용하세요. 문제 해결 npx @capgo/cli@latest app debug CI/CD pipeline에서 __CAPGO_KEEP_0__ 업로드를 트리거하는 문제가 있는 경우:

__CAPGO_KEEP_0__ 인증 토큰이 올바르게 설정되어 있는지 확인하세요

Capgo를 사용 중이라면 Troubleshooting Capgo와 연결하여 @capgo/capacitor-data-storage-sqlite Capgo의 @capgo/capacitor-data-storage-sqlite에 대한 구현 세부 정보를 참조하십시오. Capgo의 @capgo/capacitor-data-storage-sqlite Capgo의 @capgo/capacitor-data-storage-sqlite의 원시 기능을 사용하십시오. @capgo/capacitor-file Capgo의 @capgo/capacitor-file에 대한 구현 세부 정보를 참조하십시오. Capgo의 @capgo/capacitor-file Capgo의 @capgo/capacitor-file의 원시 기능을 사용하십시오. @capgo/capacitor-업로더 capgo/capacitor-업로더 구현 세부 사항에 대한 자세한 내용입니다.