Capacitor 9는 현재 next dist-tag를 통해 제공되며 정식 출시를 준비 중입니다. 알파 버전이 나왔다고 해서 즉시 앱을 업그레이드할 필요는 없지만, 공식 Capacitor 9 업데이트 가이드 및 플러그인 업데이트 가이드 미리 대응할 만한 툴체인 최소 요구 사항과 API 제거 항목은 이미 안내되어 있습니다.
이 글은 준비 체크리스트: Capacitor 8(또는 브랜치)에서 할 수 있는 작업으로, 그래야 최종 bunx cap migrate 전환 작업이 고통스럽기보다 지루하게 끝납니다. 전환할 준비가 되면 위에 링크된 Ionic 가이드를 한 줄 한 줄 따라가세요.
툴체인 및 플랫폼 최소 요구 사항 (앱)
이 최소 요구 사항에 맞춰 CI, 로컬 머신, 스토어 파이프라인을 계획하세요:
| 영역 | Capacitor 9 요구 사항 |
|---|---|
| Node.js | 24+ (최신 LTS 권장; npm 11에는 Node 24가 포함됩니다) |
| Xcode | 27+ |
| iOS 배포 대상(deployment target) | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
iOS에서 여전히 Capacitor 8.4 이하 버전을 사용 중이라면 다음 사항도 필요합니다: UIScene 생명주기 Cap 9 이전의 Capacitor 8.5 업데이트를 통해 적용되어야 합니다. Xcode 27에서 이를 요구하기 때문입니다. 이미 8.5 버전을 사용 중이라면 이 단계는 건너뛰어도 됩니다.
iOS의 경우, Swift 6 (Xcode 27 포함)에서는 다음을 허용하지 않습니다: @UIApplicationMain; 업그레이드 시 다음으로 교체하세요: @main 에서 AppDelegate.swift 공식 가이드에 설명된 대로 진행하세요.
앱 동기화 시점의 Cordova(플러그인 준비 단계 아님)
Capacitor 9에서 Cordova 호환 레이어는 다음 경우에만 앱에 연결됩니다: cap sync 설치된 Cordova 플러그인이 감지될 때. Android는 플러그인이 없으면 추가 Gradle 모듈을 제거하며, iOS는 CapacitorCordova Podfile에 추가하는 것을 중단하거나 Package.swift 플러그인이 없을 때.
이는 업그레이드 후 앱 레벨 동작 변경입니다. 아직 Cap 8을 사용 중이라면 템플릿에서 Cordova를 미리 걷어낼 필요는 없습니다. 다만, 다음을 점검하세요: 커스텀 네이티브 code (직접 만들었거나 포크한 플러그인)이 프로젝트에 실제 Cordova 플러그인이 없는데도 Cordova 심볼을 import하는지 — 선택적 Cordova 연결이 적용되면 해당 참조는 실패합니다.
Android: gradle.properties 및 AGP 9 기본 설정
AGP Upgrade Assistant는 종종 빌드가 gradle.properties AGP 8 동작을 유지하도록 명시적인 플래그를 작성합니다. Capacitor 9 앱은 제거해야 해당 항목을 그대로 유지하는 대신 제거해야 합니다. 대부분은 AGP 10 이전에 deprecated되며, 일부는 Capacitor 9 빌드를 깨뜨립니다 (예를 들어, android.builtInKotlin=false AGP 9에 포함된 Kotlin 지원을 비활성화하거나, android.sdk.defaultTargetSdkToCompileSdkIfUnset=false AGP의 추론 기능을 중단시킵니다. targetSdkVersion).
마이그레이션 시 다음 사항도 준비하세요:
- 버전 업그레이드
variables.gradle최소 버전 상향 (compile/target SDK 37,minSdkVersion26, 업데이트된 AndroidX 버전 — 공식 문서 참조). - 명시적 설정 제거
targetSdkVersion앱에서 제거하여build.gradleAGP 9가 다음에서 추론할 수 있도록compileSdkVersion. - 선언
variables.gradle상단에 있는 심볼app/build.gradle(Gradle 9.6부터 루트 프로젝트에서의 암시적 조회가 deprecated 됩니다). - 기본 ProGuard 파일 이름을 변경하고, 다음으로 마이그레이션
core-ktx로androidx.core:core1.19.0+ 버전부터는 standalone Kotlin Gradle plugin 사용을 중단하고, 다음을 제거jcenter().
다음에서 diff hunks를 확인할 수 있습니다 9.0으로 업데이트하기 Android 섹션을 참고하여 Capacitor 버전을 올리기 전에 브랜치에서 동일한 정리 작업을 적용하세요.
CLI: cap run --url
Capacitor 9에서는 live-reload host/port/https 플래그를 하나의 --url 인자로 병합합니다. 기존 방식 대신:
bunx cap run android -l --host 192.168.1.181 --port 5173개발 서버가 출력하는 URL을 전달하세요:
bunx cap run android --url http://192.168.1.181:5173/업그레이드 후 몸에 익은 습관이 새 CLI과 충돌하지 않도록, 지금 스크립트와 README 스니펫을 업데이트하세요.
공식 플러그인: Push와 Splash 주의사항
프로덕션 앱에서 자주 나타나는 사용자에게 보이는 변경 사항 두 가지:
푸시 알림 (iOS): 더 이상 사용되지 않는 alert presentation 옵션이 제거되었습니다. 대신 banner 및/또는 list 를 presentation 옵션에 사용하세요.
스플래시 화면 (Android): 기본값 launchFadeOutDuration 변경 사항: 200ms에서 0ms로. 페이드 아웃 효과를 이용해 첫 화면 렌더링 오류를 가렸다면, launchFadeOutDuration: 200 를 명시적으로 설정하세요. capacitor.config 시작 UI를 조정할 때까지 유지해야 합니다.
다음 가이드의 플러그인 섹션을 확인하여 9.0 업데이트 가이드에서 사용 중인 공식 플러그인의 AndroidX 및 Google Play Services 버전 업데이트를 확인하세요.
플러그인 관리자: Cap 8 호환성을 유지하며 Cap 9를 준비하세요.
만약 Capacitor 8에서 사용되는 Capacitor 플러그인을 배포한다면 및 Cap 9를 지원하는 code를 원한다면, 다음 사항에 집중하세요: 사용 중단된 API 제거Cap-9 전용 패키징 변경 사항이 아닌,
Cap 8이 지원되는 동안 안전하게 수행할 작업:
- 교체
@NativePlugin포함@CapacitorPlugin및 기존 permission / activity-result API를 다음으로 마이그레이션:@PermissionCallback/@ActivityCallback패턴(다음 참조) plugin 9.0 가이드 표 참조). - 제거
PluginCall.hasOption,Plugin.getConfigValue, 이전CapConfig생성자 및 getter,PluginCall.save()/isSaved(), 그리고 “code의 Breaking changes”에 나열된 기타 Java 제거 사항들입니다. - iOS에서는 다음 사용을 중단하세요:
CAPBridge호환성 클래스 및 deprecated된CAPBridgeProtocol헬퍼; 대신ApplicationDelegateProxy, 타입이 지정된PluginCall액세서 및 마이그레이션 테이블의 bridge 속성을 사용하세요. - 실행하세요
bunx @capacitor/plugin-migration-v8-to-v9@latest브랜치에서 작업하며, Cap 9 메이저 버전을 배포하기 전까지는 Cap 8 peer dependencies와 컴파일이 가능한 API 수정 사항만 유지하세요.
다음 항목을 제거하지 마세요: Cordova 플러그인의 SPM product Package.swift Capacitor 8 버전을 여전히 지원하는 동안에는요. 플러그인이 SPM 기반인 경우 Cap 8 프로젝트는 해당 의존성을 필요로 합니다. 너무 일찍 제거하면 8 버전을 사용하는 사용자들에게 문제가 생깁니다. 따라서 선택적 Cordova 사용 또는 무조건적인 제거를 Cordova 제품 로서 Capacitor 9 전용 릴리스 라인(또는 Cap 9+로 명시된 semver major)으로 취급하세요. 이는 Cap 8 지원을 중단한 후에 이루어져야 하며, 플러그인 가이드에 명시된 대로 Cap 8 라인에서 미리 작업하는 것이 아닙니다.
버전을 올릴 때도 동일한 원칙이 적용됩니다. capacitor-swift-pm 로 9.0.0-alpha.x 에서 Package.swift: 이는 Cap 8 호환 릴리스가 아닌, Cap 9 메이저 버전에 포함되어야 합니다.
Capgo live updates 및 네이티브 Cap 9 스토어 빌드
Capgo는 web bundle OTA 방식으로 업데이트를 제공하며, native shell은 여전히 App Store와 Google Play를 통해 배포됩니다. 앱을 Capacitor 9로 마이그레이션할 때는 다음과 같이 진행하세요:
- 배포 최소 하나 이상의 스토어 빌드를 Capacitor 9 native 프로젝트(iOS 및 Android)로 컴파일해야 합니다. 이 바이너리가 Capgo 채널이 타겟팅할 native baseline을 설정합니다.
- 해당 빌드가 사용자에게 배포된 이후에만, Cap 9 WebView 및 플러그인 동작에 대해 테스트를 마친 OTA bundle을 사용해야 합니다.
- 프로덕션 채널을
metadata전략에 따라 설정하고, 각 채널에 일치하는 Cap 9 bundle을 다음을 사용하여 upload 하세요:--auto-min-update-version. 의도적인 native baseline upload를 위해, 다음은 제외하세요:--fail-on-incompatible(native package는 변경될 수 있습니다).--fail-on-incompatible및--auto-min-update-version이후 매일 OTA upload를 진행하세요. 자세히 보기: Native + OTA 채널 워크플로우. - 채널과 semver 규칙을 일치시켜, 이전 버전의 native shell을 사용하는 기기에 Capacitor 9 API를 사용하는 bundle이 배포되지 않도록 주의하세요.
만약 Capgo Build 또는 자체 CI를 사용한다면, 에이전트를 갱신하세요 하기 전에 Cap 9 스토어 출시 전에 갱신하여 파이프라인이 사용자가 설치하는 버전과 일치하도록 하세요: macOS runner에는 Node 24+ 및 Xcode 27+가 필요합니다; Linux 러너에는 Node 24+ 버전과 다음 버전과 호환되는 Android 툴링이 필요합니다: AGP 9.2.1 / Gradle 9.5.1 (Xcode는 macOS 전용입니다).
권장 작업 순서
- 설치된 툴링 업그레이드 CI 호스트 및 개발자 환경의 툴(Node, Xcode, Android Studio, JDK)을 위 버전으로 업그레이드하세요. 주의사항: Cap 8 앱의 AGP 의존성, Gradle wrapper 또는 기타 Android 프로젝트 파일을 Cap 9 버전으로 미리 올리지 마세요.
bunx cap migrate— 해당 프로젝트 변경 사항은 마이그레이션 단계에서 진행해야 합니다. - 사용 중단된 native API 수정 앱 code 및 플러그인 내의 API(특히 커스텀
AppDelegateURL 처리 및 Android bridge 사용 방식). - Android Gradle 정리 파일 및 스크립트 (
gradle.properties, ProGuard 기본 설정,--url개발 스크립트 내). - Cordova 감사 앱 레벨에서 사용 현황을 확인하세요. Cap 9 전용 릴리스가 나오기 전까지는 plugin SPM Cordova 제품을 변경하지 마세요.
- Cap 9이 GA(정식 출시)되면 (또는 출시 후
next),bun add -d @capacitor/cli@next를 실행하거나 (@latest이후에), 그 다음bunx cap migrate를 수행하고, 9.0 버전 업데이트. - Cap 9 Native Build를 스토어에 배포한 후, 해당 채널에서 Capgo OTA 롤아웃을 재개하거나 확장하세요.
Capacitor 9 버전은 주로 "더 이상 사용되지 않는 기능(deprecation)을 정리하고 최신 Android 및 Apple 툴체인에 맞추는 작업"에 집중합니다. Cap 8에서 미리 이 작업을 해두면 업그레이드 시 코드 차이(diff)를 줄일 수 있고, 여전히 8.x 버전을 사용하는 팀들의 플러그인과도 호환성을 유지할 수 있습니다.
