Capacitor 9는 next dist-tag에서 일반 가용성(GA)으로 이동 중입니다. 알파 버전이 출시되는 날 바로 앱을 업그레이드할 필요는 없지만, 공식 Capacitor 9 업데이트 가이드 및 플러그인 업데이트 가이드 미리 대응할 만한 툴체인 최소 요구 사항과 API 제거 항목은 이미 안내되어 있습니다.
이 글은 준비 체크리스트: Capacitor 8(또는 브랜치)에서 할 수 있는 작업으로, 그래야 최종 bunx cap migrate 전환 작업이 고통스럽기보다 지루하게 끝납니다. 전환할 준비가 되면 위에 링크된 Ionic 가이드를 한 줄 한 줄 따라가세요.
툴체인 및 플랫폼 최소 요구 사항 (앱)
이 최소 요구 사항에 맞춰 CI, 로컬 머신, 스토어 파이프라인을 계획하세요:
| 영역 | Capacitor 9 요구 사항 |
|---|---|
| Node.js | 24+ (최신 LTS 권장; npm 11에는 Node 24가 포함됩니다) |
| iOS 프로파일링 | 27+ |
| iOS 배포 대상 | 16.0+ |
| 디버깅하기 | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
iOS에서 아직 Capacitor 8.4 이하 버전을 사용 중이라면 다음도 필요합니다 UIScene 라이프사이클 Capacitor 8.5 업데이트에서 작동하도록 하세요. Cap 9 이전 단계이며, 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에서 비추천되며, 일부는 Cap 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은 루트 프로젝트의 암시적 조회를 비추천합니다). - 기본 ProGuard 파일 이름을 교체하고, 마이그레이션합니다
core-ktx대상androidx.core:core1.19.0 이상, 독립형 Kotlin Gradle 플러그인 사용 중단 및 제거jcenter().
diff hunk를 다음에서 읽을 수 있습니다: 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 에서 200 ms에서 0으로 변경. 페이드로 첫 페인트 글리치를 가렸다면 launchFadeOutDuration: 200 을(를) 명시적으로 설정하세요 capacitor.config 스타트업 UI를 조정할 때까지.
플러그인 섹션을 스캔하여 9.0 업데이트 가이드 에서 사용하는 공식 플러그인과 관련된 AndroidX 및 Google Play Services 버전 업데이트를 확인하세요.
플러그인 유지보수자: Cap 8에서 깨지지 않도록 Cap 8 대비 준비
Capacitor 8에서 사용되는 Capacitor 플러그인을 배포하는 경우 및 Cap 9에 대비한 code를 원한다면 비추천 API 제거에 집중하세요. Cap 9 전용 패키징 변경 사항은 아닙니다.
Cap 8이 지원되는 동안 안전하게 수행할 수 있는 작업:
- 교체
@NativePlugin포함@CapacitorPlugin레거시 권한/액티비티-결과 API를 다음으로 마이그레이션하고@PermissionCallback/@ActivityCallback패턴을 사용하세요(참고: 플러그인 9.0 가이드 표). - 제거
PluginCall.hasOption,Plugin.getConfigValue, 구버전CapConfig생성자와 getter,PluginCall.save()/isSaved()및 “code의 Breaking changes” 섹션에 나열된 기타 Java 제거 항목. - iOS에서는 다음을 사용하지 마세요:
CAPBridge호환성 클래스와 비추천CAPBridgeProtocol헬퍼 대신ApplicationDelegateProxy, 타입 지정된PluginCallmigration 테이블의 accessors 및 bridge 프로퍼티입니다. - 실행
bunx @capacitor/plugin-migration-v8-to-v9@latest브랜치에서 작업하고, Cap 9용 major를 게시할 때까지 Cap 8 peer dependencies와 여전히 컴파일되는 API 수정 사항만 유지하세요.
다음은 제거하지 마세요: Cordova 플러그인의 SPM 프로덕트를 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는 웹 번들 업데이트를 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 업로드에 영향을 미치지 않습니다. 참고 네이티브 + OTA 채널 워크플로. - 채널과 semver 규칙을 일치시켜, Cap 9 API를 전제로 한 번들을 구형 네이티브 셸을 실행 중인 기기에 배포하지 않도록 하세요.
사용 중이라면 Capgo 빌드 또는 자체 CI에서 에이전트를 새로고침 첫 번째 제출이 승인되기 사용자가 설치하는 버전과 파이프라인이 일치하도록 Cap 9 스토어 릴리스: macOS가 러너에는 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— 해당 프로젝트 변경 사항은 마이그레이션 단계에서 처리해야 합니다. - 비추천 네이티브 API 수정 앱 code 및 플러그인(특히 커스텀
AppDelegateURL 처리 및 Android bridge 사용). - Android Gradle 정리 파일 및 스크립트 (
gradle.properties, ProGuard 기본 설정,--urldev 스크립트 내). - 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를 배포하는 팀과도 플러그인 호환성을 유지할 수 있습니다.