Capgo의 버전 이름은 처음에는 거꾸로 느껴질 수 있습니다: version_build 는 네이티브 앱의 기준이 되며, version_name 는 기기에서 번들을 추적합니다. 이 차이를 제대로 이해하면 번들을 배포하기 전에 특정 기기가 OTA 업데이트를 받을지, 못 받을지 확인할 수 있습니다.
자사 플랫폼을 포함한 5개 라이브 업데이트 플랫폼의 트러블슈팅 페이지를 분석한 결과, 저희 문서에는 이름이 붙은 version_build 불일치 코드가 7개 있는 반면, 나머지 4개 플랫폼은 각각 5개, 2개, 2개, 0개였습니다. 이름이 붙은 코드가 많을수록 version_build 불일치가 발생했을 때 추측할 일이 줄어듭니다.
목차
- 1단계: Capgo에서 version_build 및 version_name 찾기
- 2단계: 네이티브 베이스라인과 다운로드된 번들 식별
- 3단계: 네이티브 앱 버전의 출처 확인
- 4단계: Capgo가 수신하는 번들 버전 설정 및 검증
- 5단계: 업데이트 배포 전 채널 적합성 테스트
- 6단계: 버전 불일치 진단 및 릴리스 재현성 확보
- 자주 묻는 질문
- 마치며
1단계: Capgo에서 version_build 및 version_name 찾기
먼저 이 둘을 하나의 앱 설치에 대한 서로 다른 사실로 보세요. version_build 기기에 설치된 네이티브 앱 버전을 Capgo에 알려줍니다. version_name 기기가 다운로드한 JavaScript 번들을 Capgo에 알려줍니다. 두 값은 서로 다를 수 있고, 흔히 예상되는 일입니다.
Capgo의 버전 모델에서 native version은 업데이트 대상 여부를 결정하는 기준점입니다. Capgo은 채널에 할당된 bundle을 이 native baseline과 비교합니다. 기기에 설치된 bundle version은 현재 웹 code를 식별하는 데 도움이 되지만, 채널 버전 규칙의 기준이 되는 native baseline을 대체하지는 않습니다.
문제 해결 전에 Capgo 콘솔의 Devices 페이지에서 기기를 조회해 두 값을 모두 기록하세요. 그런 다음 채널의 target bundle과 비교하세요. Capgo 채널 규칙은 채널의 target version이 무엇과 비교되어 확인되는지 설명합니다. version_build.
| 값 | 의미 | 답변에 활용 | 일반적인 출처 |
|---|---|---|---|
version_build |
Capgo로 전송된 Native app baseline | 이 native app이 채널의 target bundle을 받을 수 있나요? | Native app version 또는 명시적인 Capacitor 설정값 |
version_name |
현재 다운로드된 JavaScript bundle | 현재 어떤 번들 버전이 설치되어 있나요? | 업로드 시 결정된 번들 버전 |
| 채널 타겟 | 디바이스의 채널에 할당된 번들 | Capgo가 업데이트를 확인하는 버전은 무엇인가요? | 현재 채널 할당 |
릴리스 노트나 테스트 보고서에서는 세 값을 각각 별도 컬럼에 두세요. 팀에서 그냥 “앱 버전” 하나로 적으면 잘못된 쌍을 비교하기 쉽습니다. 적용 가능 여부를 확인하려면 타겟 번들을 다음 항목과 비교하세요. version_build. 설치된 웹 code의 경우, 다음을 확인하세요. version_name.
Capgo의 명명 방식은 팀이 증가하는 빌드 번호를 뜻할 때 “build”를 자주 쓰는 Android 관례와 다르게 보일 수 있습니다. 여기서는 이름이 암시하는 대로가 아니라 Capgo 역할을 기준으로 필드를 읽으세요. 이 작은 습관이 릴리스 현장의 혼선을 크게 줄여줍니다.
2단계: 네이티브 베이스라인과 다운로드된 번들 식별
버전 값을 변경하기 전에, 어떤 code가 네이티브이고 어떤 code이 번들로 제공되는지 파악하세요. 네이티브 앱은 설치된 iOS 또는 Android 바이너리입니다. 번들에는 Capacitor 앱이 OTA 업데이트를 통해 받을 수 있는 웹 에셋이 포함됩니다.
기준 버전으로 출시된 네이티브 앱을 가정해 봅시다. 1.2.3. 이후 웹 수정 사항은 bundle로 업로드됩니다 1.2.4. Capgo가 채널의 대상 bundle이 네이티브 베이스라인에 허용되는지 확인합니다 1.2.3. 대상이 충족되면 기기가 해당 bundle을 다운로드할 수 있습니다. 설치 후 version_name 기기에 있는 bundle이 반영됩니다. 네이티브 베이스라인은 설치된 바이너리와 연결된 상태로 유지됩니다.
이 차이는 사용자가 구형 앱 스토어 빌드를 사용 중인데 더 새로운 웹 bundle을 가진 경우 중요합니다. bundle은 네이티브 바이너리를 교체하지 않고 변경할 수 있지만, OTA 업데이트는 앱에 포함되지 않았던 네이티브 code를 추가할 수 없습니다. 변경 사항에 새로운 플러그인이나 네이티브 설정이 필요하면 bundle 업로드를 대체 수단으로 삼기보다 네이티브 빌드를 계획하세요.

값이 동기화되지 않은 것처럼 보일 때 이 빠른 확인을 사용하세요:
- 테스트 기기에 설치된 네이티브 바이너리를 확인하세요.
- Capgo가 네이티브 베이스라인으로 받는 버전 값을 찾으세요.
- 기기의 채널에 할당된 bundle 버전을 확인하세요.
- 설치된 bundle 버전을 나머지 두 값과 별도로 기록하세요.
다음 값에서 네이티브 베이스라인을 추측하지 마세요: package.json 빌드 프로세스가 해당 값을 네이티브 버전이나 Capgo 설정으로 의도적으로 복사하는 경우가 아니라면요. JavaScript 프로젝트 버전과 스토어에 설치된 앱 버전은 달라질 수 있습니다. 올바른 소스는 앱이 실제로 Capgo에 전송하는 값입니다.
베이스라인과 현재 bundle을 식별할 수 있게 되면, 다음 단계는 각 값을 소스 파일로 추적하는 것입니다. 플랫폼별 차이가 드러나는 곳이기도 합니다.
3단계: 네이티브 앱 버전의 출처 확인
신뢰할 수 있는 version_build를 위해, Capacitor 앱이 보고하는 네이티브 버전을 찾으세요. Capgo의 버전 문서에는 iOS와 Android의 서로 다른 소스 키가 설명되어 있으며, 결과된 네이티브 값을 OTA 비교 베이스라인으로 사용합니다.
iOS의 경우
체크 항목 CFBundleShortVersionString 앱의 Info.plist에 있습니다. 대부분의 Xcode 프로젝트에서 이 키는 다음과 같이 설정되어 있습니다: $(MARKETING_VERSION), 따라서 실제로 수정하는 값은 타겟의 Marketing Version입니다. 템플릿이나 빌드가 덮어쓸 수 있는 파일에서만 확인하지 말고, 빌드된 앱에서도 값을 확인하세요.
팀이 Xcode 프로젝트를 업데이트했지만 앱에 전달되는 값은 변경하지 않은 경우, 로컬 프로젝트 뷰는 정상으로 보일 수 있지만 설치된 바이너리는 다른 값을 보고할 수 있습니다. 생성된 네이티브 앱의 버전을 릴리스 프로세스에서 기대하는 값과 비교하세요.
Android에서
체크 항목 defaultConfig.versionName Android 앱의 Gradle 설정에 정의됩니다. 이 네이티브 version name은 Capgo의 OTA 비교에 사용됩니다. Android build code이나 관련 없는 JavaScript 패키지 버전과 혼동하지 마세요. 이 체크에서 중요한 것은 네이티브 앱이 어떤 version name을 보내는지입니다.
공통 버전 정책은 두 플랫폼이 일관되게 유지되는 데 도움이 되지만, 이미 하나의 소스를 공유한다고 가정하지 마세요. iOS와 Android는 파일, 빌드 단계, 출시 시점이 각각 다를 수 있습니다. 특히 한 플랫폼의 스토어 출시 일정이 다르면, 출시 체크에서 최종 값을 비교하세요.
일부 앱은 네이티브 버전을 명시적으로 설정합니다: capacitor.config.ts updater 설정의 version 값을 통해서입니다. 이 Capgo Semver Tester 설정 또는 네이티브 앱 메타데이터에서 올 수 있는 값으로 이 네이티브 베이스라인을 설명합니다. 앱이 네이티브 메타데이터를 오버라이드한다면, 스토어 버전이 소스라고 여기지 않도록 그 선택을 문서화하세요.
각 플랫폼마다 소스 파일, 확정된 값, 해당 값이 포함된 빌드를 기록해 두세요. 이렇게 하면 테스터 기기에 설치된 앱보다 레포지토리에 이미 더 최신 버전이 있을 수 있는 출시 후에 불일치를 더 쉽게 추적할 수 있습니다.
빌드가 실제로 읽는 소스만 변경하세요. 오래된 파일을 수정하면 패키징된 네이티브 버전은 그대로 둔 채 code 리뷰만 완료된 것처럼 보이게 할 수 있습니다.
4단계: Capgo가 수신하는 번들 버전 설정 및 검증
Bundle 버전은 설치된 네이티브 바이너리가 아닌 JavaScript 업데이트를 설명합니다. Capgo은(는) 이 버전을 version 의 package.json 필드에서 가져올 수 있습니다(명시적인 bundle 버전을 제공하지 않는 경우). CLI의 --bundle 옵션은 업로드 시 전송되는 버전을 설정할 수 있습니다.
하나의 경로를 선택하고 릴리스 프로세스에서 명확히 하세요. 만약 package.json 이 소스라면 업로드 전에 해당 필드를 증가시키세요. CI가 CLI를 통해 bundle 버전을 전달하는 경우, 해당 작업이 릴리스 로그에 해결된 버전을 출력하도록 하세요. 두 경로를 조용히 혼합하면 채널이 특정 값을 받은 이유를 파악하기 어려워집니다.
익숙한 major.minor.patch 형식의 시맨틱 버전링을 사용하세요. 예를 들어 1.2.3. Capgo 채널 전략은 네이티브 베이스라인에 대상 bundle이 적합한지 결정하기 위해 해당 버전의 각 부분을 사용합니다. 프리릴리스 접미사(예: -beta.1 채널별 빌드를 라벨링하는 데 도움이 되지만, 릴리스 도구 전반에서 버전이 파싱 가능하고 일관되도록 유지하세요.
게시 전에 증분 방식을 미리 고려하세요:
- 같은 릴리스 라인 내에서 호환되는 웹 수정은 패치 변경을 사용하세요.
- 새로운 호환 기능 라인에 속하는 변경 사항이라면 minor 버전을 사용하세요.
- 호환성 경계가 바뀌어 이전 native code이 번들을 지원하지 않을 수 있다면 major 버전을 사용하세요.
이 라벨들은 팀 컨벤션일 뿐, OTA로 네이티브 기능을 추가하는 수단이 아닙니다. 버전 번호만으로는 번들이 네이티브 앱에서 안전한지 증명할 수 없습니다. 실제 호환성 결정은 바이너리에 포함된 code와 의존성에 맞춰 관리해야 합니다.
upload 전에 패키지 버전이나 CLI 값을 upload 후 번들에 표시되는 버전과 비교하세요. 번들이 배포될 채널도 확인해야 합니다. 이름이 올바른 번들이라도 의도하지 않은 채널에 upload하면 잘못된 테스트 결과가 나올 수 있습니다.
잘못되었거나 일관성 없는 문자열은 추측하지 말고 바로 확인해야 합니다. 검증된 릴리스 값을 유지하고, 소스를 수정한 뒤, 배포 전에 해석된 버전을 테스트하세요.
이 Capgo CLI 명령어 레퍼런스 bundle 버전이 릴리스 명령어의 입력값 중 하나이므로, upload를 스크립트에 연결할 때 유용합니다.
5단계: 업데이트 배포 전 채널 적합성 테스트
채널 적합성은 어떤 번들이 더 최신으로 보이는지 추측하는 게 아니라 비교로 판단합니다. Capgo은 채널의 타겟 번들을 다음 값으로 전달되는 네이티브 베이스라인과 비교합니다: version_build. 현재 다운로드된 번들은 다음 값으로 보고되며 version_name해당 채널 규칙의 베이스라인은 아닙니다.
예를 들어, 설치된 네이티브 앱이 보고하는 버전이 1.2.3이고, 현재 번들이 1.2.4라고 가정해 보겠습니다. 채널이 1.2.5를 가리킨다면, 대상 버전을 현재 번들이 아닌 네이티브 베이스라인과 비교하여 평가해야 합니다 1.2.3, 단순히 현재 번들과만 비교해서는 안 됩니다 1.2.4. 허용되는 대상 버전은 채널의 업데이트 전략에 따라 달라집니다.
Capgo는 네이티브 베이스라인에 대한 업데이트를 제한하는 major, minor 등의 전략을 문서화합니다. major 전략을 사용할 경우, major 버전이 더 높은 대상이 차단될 수 있습니다. minor 전략을 사용할 경우, 베이스라인의 major 또는 minor 라인이 변경되는 대상이 차단될 수 있습니다. 모든 최신 버전처럼 보이는 번드가 허용된다고 가정하기보다, 설정된 전략을 확인하세요.

릴리스할 정확한 조합을 테스트하세요:
- 대상 사용자를 나타내는 네이티브 빌드를 설치하세요.
- Capgo에 전송된 네이티브 베이스라인을 확인하세요.
- 테스트 기기를 의도된 채널에 할당하세요.
- 채널 대상 및 해당 버전 전략을 확인하세요.
- 업데이트를 요청하고 기기의 결과를 확인하세요.
사용자 기반에 사용 중인 스토어 버전이 하나 이상이라면 다른 네이티브 베이스라인에서도 동일한 검사를 실행하세요. 새 빌드에서는 작동하는 번들이 오래된 바이너리에서는 차단될 수 있으며, 이는 의도된 안전 규칙일 수 있습니다.
더 넓은 배포를 위해 테스트 채널이나 제한된 롤아웃으로 시작하세요. 대상 범위를 확장하기 전에 예상치 못한 대상 자격 결과를 주시하세요. Capgo의 채널 모델은 팀이 릴리스 채널을 통해 번들을 전달할 수 있게 합니다. 릴리스 노트에서 각 채널의 대상과 의도된 네이티브 라인을 명확히 유지하세요.
테스트 기기가 업데이트되지 않으면 다시 업로드하기 전에 채널 할당 및 버전 값을 확인하세요. 동일한 번들을 반복적으로 게시해도 베이스라인 불일치를 해결할 수 없습니다.
6단계: 버전 불일치 진단 및 릴리스 재현성 확보
값이 예상과 일치하지 않으면 순서대로 추적하세요. 먼저 기기의 네이티브 앱 버전을 확인하세요. 다음으로 설정 오버라이드가 베이스라인을 변경하는지 확인하세요. 그런 다음 Capgo가 받은 번지 버전과 채널 대상을 비교하세요. 이 순서는 잘못된 소스 값과 설정대로 작동하는 채널 규칙을 구분합니다.
일반적인 원인은 버전 증가 package.json 네이티브 버전은 그대로 두면서 다른 릴리스 브랜치에서 한 플랫폼을 빌드하고, 다른 채널에 할당된 디바이스를 테스트하는 경우입니다. 혼란의 또 다른 원인은 모든 숫자를 '빌드 버전'이라 부르는 것입니다. 어떤 값이 네이티브인지, 업로드된 번들인지, 현재 설치된 것인지 기록해 두세요.
CI/CD에서는 버전 입력을 명시적으로 처리하세요. 파이프라인이 제어된 소스에서 의도된 릴리스 버전을 읽은 후, 업로드 명령에 전달하거나 업로드 단계 전에 패키지 필드를 업데이트하세요. 해결된 네이티브 베이스라인과 번들 타깃을 작업 출력에 기록하세요. 빌드 서버에서 볼 수 없는 개발자의 로컬 상태에 의존하지 마세요.
필수 버전이 누락되었거나 팀이 허용하지 않는 형식인 경우 실패하는 릴리스 게이트를 사용하세요. 그 다음 프로모션 전에 올바른 채널로 테스트 업로드를 실행하세요. Capgo은 CLI 기반 배포 플로우를 지원하므로, 팀은 번들 업로드를 기존 CI/CD 작업에 포함시키고 가시적인 명령 로그를 유지할 수 있습니다.
이 값들을 Android WebView 엔진 버전과 혼동하지 마세요. 저희 @capgo/capacitor-webview-version-checker 플러그인은 디바이스의 WebView 엔진이 구형인지 확인하고 네이티브 업데이트 프롬프트를 표시할 수 있습니다. 이는 version_build 및 version_name과는 별개의 문제이므로, 네이티브 베이스라인과 채널의 타깃 번들을 확인하는 것을 대체하지 않습니다.
레거시 스킴에서 마이그레이션할 때는 기존 값의 이름을 한 번에 모두 바꾸지 마세요. 먼저 기존 native version을 native baseline에 매핑하세요. 그다음 업로드된 web release를 bundle version에 매핑하세요. 사용자를 해당 채널로 유도하기 전에 대표적인 기존 앱 빌드로 채널 전략을 테스트하세요.
소스 커밋, native version, 업로드된 bundle version, channel, 테스트 결과를 포함한 간단한 릴리스 기록을 남기세요. 릴리스를 일시 중지하거나 롤백해야 할 때 이 기록이 있으면 팀이 어떤 bundle이 어디로 갔는지 파악할 수 있습니다. 또한 다음 배포를 누군가가 어떤 파일을 변경했는지 기억하는 데 의존하지 않고 반복 가능하게 만듭니다.
자주 묻는 질문
Capgo에서 version_build와 version_name의 차이점은 무엇인가요?
version_build 는 네이티브 앱의 기준이 되며, version_name 현재 다운로드된 bundle version입니다. Capgo은 채널의 대상 bundle이 조건에 맞는지 확인할 때 native baseline을 사용합니다. 어떤 native app이 설치되어 있고 어떤 web bundle을 가지고 있는지 구분할 수 있도록 로그와 릴리스 노트에서 두 값을 별도로 유지하세요.
version_name이 OTA 업데이트 허용 여부를 결정하나요?
아니요, Capgo의 channel version 전략은 대상 bundle을 다음 값과 비교합니다: version_build즉, native baseline입니다. version_name 현재 다운로드된 bundle을 식별합니다. 기기가 업데이트를 받지 못한다면 현재 bundle 값을 변경하기 전에 해당 기기의 baseline, channel target, 설정된 전략을 확인하세요.
Capgo는 네이티브 버전을 어디에서 가져오나요?
iOS에서 Capgo이 읽는 값은 CFBundleShortVersionString, Xcode가 보통 자동으로 채워 넣는 값입니다 MARKETING_VERSION. Android에서는 네이티브 버전이 다음에서 가져옵니다 defaultConfig.versionName. Capacitor 설정에서 명시적인 업데이트 버전을 지정하면 앱이 전송하는 값이 변경될 수 있으므로, 빌드된 앱을 확인하세요.
Capgo는 번들 버전을 어디에서 가져오나요?
Capgo은 다음을 사용할 수 있습니다 version 의 package.json 필드를 명시적인 번들 버전을 전달하지 않을 때 사용할 수 있습니다. 또한 CLI의 --bundle 옵션으로 버전을 제공할 수도 있습니다. 릴리스 워크플로우에서 하나의 명확한 출처를 선택한 후, 업로드 후 Capgo가 받은 버전을 확인하세요.
마치며
사용 version_build 네이티브 베이스라인용 version_name 설치된 번들용. 다음 롤아웃 전에 테스트 디바이스에서 두 값을 모두 확인하고, 채널 대상과 베이스라인을 비교하세요. 이 한 번의 확인으로 더 넓은 대상에게 도달하기 전에 버전 불일치를 잡아낼 수 있습니다.