본문 바로가기
Capacitor

Capacitor 9 준비하기: 앱과 플러그인 팀이 지금 할 수 있는 일

Capacitor 9는 Node, Xcode, Android Gradle, deprecated native API에 대한 기준을 높입니다. 버전을 전환하기 전에 Cordova 선택적 동기화, CLI live reload, Capgo OTA 스토어 빌드를 포함해 Capacitor 8에서 준비하는 방법을 알아보세요.

Capacitor 9 준비: 앱 및 플러그인 팀이 지금 할 수 있는 것 Capgo 블로그 일러스트

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, minSdkVersion 26, 업데이트된 AndroidX 버전 — 공식 문서 참조).
  • 명시적 targetSdkVersion 을(를) 앱에서 제거하여 build.gradle AGP 9가 에서 추론할 수 있도록 합니다 compileSdkVersion.
  • 을(를) 선언합니다 variables.gradle 상단의 app/build.gradle (Gradle 9.6은 루트 프로젝트의 암시적 조회를 비추천합니다).
  • 기본 ProGuard 파일 이름을 교체하고, 마이그레이션합니다 core-ktx 대상 androidx.core:core 1.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, 타입 지정된 PluginCall migration 테이블의 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로 마이그레이션할 때:

  1. 배포 최소 하나의 스토어 빌드를 Capacitor 9 native 프로젝트(iOS 및 Android)에 맞춰 컴파일해야 합니다. 이 바이너리가 Capgo 채널이 대상으로 하는 native baseline을 설정합니다.
  2. 해당 빌드가 사용자에게 배포된 후에만 Cap 9 WebView와 플러그인 동작을 기준으로 테스트한 OTA bundle에 의존해야 합니다.
  3. 프로덕션 채널을 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 채널 워크플로.
  4. 채널과 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 전용입니다.)

권장 작업 순서

  1. 설치된 도구 업그레이드 CI 호스트 및 개발자 머신에서 위의 최소 버전(Node, Xcode, Android Studio, JDK)으로 업그레이드하세요. 하지 마세요 Cap 8 앱의 AGP 의존성, Gradle wrapper 또는 기타 Android 프로젝트 파일을 Cap 9 값으로 업데이트하지 마세요 bunx cap migrate — 해당 프로젝트 변경 사항은 마이그레이션 단계에서 처리해야 합니다.
  2. 비추천 네이티브 API 수정 앱 code 및 플러그인(특히 커스텀 AppDelegate URL 처리 및 Android bridge 사용).
  3. Android Gradle 정리 파일 및 스크립트 (gradle.properties, ProGuard 기본 설정, --url dev 스크립트 내).
  4. Cordova 점검 앱 레벨에서 사용 현황을 확인하세요. Cap 9 전용 릴리스가 나오기 전까지는 plugin SPM Cordova 제품을 변경하지 마세요.
  5. Cap 9이 GA(정식 출시)되면 (또는 수용할 때 next), 실행하세요 bun add -d @capacitor/cli@next (또는 @latest 릴리스 후), 그다음 bunx cap migrate, 그리고 따르세요 9.0으로 업데이트.
  6. Cap 9 Native Build를 스토어에 배포하세요 그런 다음 해당 채널에서 Capgo OTA 롤아웃을 재개하거나 확장하세요.

Capacitor 9는 주로 “deprecation을 정리하고 최신 Android 및 Apple 툴체인에 맞추는 작업”에 집중합니다. Cap 8에서 이 작업을 미리 해두면 업그레이드 diff를 작게 유지하고, 아직 8.x를 배포하는 팀과도 플러그인 호환성을 유지할 수 있습니다.

Capacitor 앱용 Live updates

웹 레이어 버그가 라이브 상태라면, 앱 스토어 승인을 며칠씩 기다리지 말고 Capgo를 통해 수정 사항을 배포하세요. 네이티브 변경 사항은 정상 리뷰 절차를 그대로 따르는 반면, 사용자는 백그라운드에서 업데이트를 받습니다.

블로그 최신 글

Capgo는 정말 프로페셔널한 모바일 앱을 만드는 데 필요한 최고의 인사이트를 제공합니다.