Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법

Capacitor 8은 기본적으로 Swift Package Manager(SPM)를 사용해 새 iOS 프로젝트를 생성합니다. 여전히 CocoaPods를 사용하는 기존 앱도 마이그레이션할 수 있지만, 가장 안전한 방법은 앱에 적용된 iOS 네이티브 커스터마이징의 범위에 따라 달라집니다.

이 가이드에서는 무엇이 바뀌고 무엇을 백업해야 하는지, 그리고 Capacitor 마이그레이션 어시스턴트를 사용하거나 SPM으로 iOS 프로젝트를 다시 스캐폴딩하는 두 가지 실용적인 마이그레이션 경로를 다룹니다.

지금 마이그레이션해야 하는 이유

CocoaPods가 읽기 전용 trunk 방식으로 전환되고 있습니다. 현재 계획에 따르면 CocoaPods trunk는 다음 시점에 새 podspec 수락을 중단할 예정입니다. 2026년 12월 2일. 기존 빌드는 계속 작동하지만, 전환 후에는 trunk에 의존하는 새 릴리스와 의존성 업데이트가 더 이상 그곳에 게시되지 않습니다.

SPM은 Capacitor이 지향하는 방향이기도 합니다. Capacitor은 Capacitor 6부터 CocoaPods 또는 SPM 선택을 지원해 왔으며, Capacitor 8부터는 iOS SPM 프로젝트를 기본 템플릿으로 생성합니다.

Capacitor SPM 프로젝트에서 달라지는 점

CocoaPods에서 SPM으로 마이그레이션하면 iOS 의존성 레이어가 교체됩니다. 웹 앱, Android 프로젝트, 그리고 대부분의 Capacitor 워크플로우 명령은 동일하게 유지됩니다.

CapApp-SPM이 Podfile을 대체합니다

CocoaPods 앱에서 iOS 의존성은 다음을 통해 연결됩니다 ios/App/Podfile, Podfile.lock, Pods/, 그리고 생성된 .xcworkspace.

SPM 앱에서 Capacitor은 다음 이름의 로컬 패키지를 생성합니다 CapApp-SPM. 이 패키지는 Capacitor이 네이티브 iOS 플러그인 의존성을 참조하는 중심 지점이 됩니다. Capacitor CLI 업데이트는 CapApp-SPM 플러그인을 동기화할 때 업데이트되므로, 생성된 결과물로 취급하고 직접 편집하지 마세요.

debug.xcconfig가 Pods 설정을 대체합니다

마이그레이션 어시스턴트는 생성된 debug.xcconfig 파일도 함께 만듭니다. 이 파일에는 CocoaPods가 생성한 xcconfig 파일을 통해 제공하던 빌드 설정이 들어 있습니다.

마이그레이션 후, 어시스턴트가 안내하면 debug.xcconfig Xcode 프로젝트 설정에 추가해야 할 수도 있습니다.

모든 플러그인은 SPM을 지원해야 합니다

동일한 Capacitor iOS 프로젝트 내에서 CocoaPods와 SPM을 혼용할 수 없습니다. 마이그레이션 전에 모든 Capacitor 및 Cordova 플러그인을 확인하세요. package.json.

플러그인이 아직 SPM을 지원하지 않는다면, 업데이트하거나 교체하거나 플러그인을 먼저 마이그레이션하세요. 간단한 Swift 플러그인은 Ionic의 capacitor-plugin-converter를 통해 변환할 수 있는 경우가 많지만, Objective-C 및 Swift 구조가 더 복잡한 플러그인은 수동 작업이 필요할 수 있습니다.

먼저 백업할 항목

iOS 프로젝트를 수정하기 전에 깨끗한 git 브랜치에서 시작해 현재 상태를 커밋하세요. 그다음 앱이 의존하는 네이티브 파일을 나열하세요.

보존해야 할 일반적인 파일에는 ios/App/ 다음이 포함됩니다:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, 앱에 해당 파일이 있는 경우
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, Firebase를 사용하는 경우
맞춤형 .xcconfig 파일 다운로드
Signing 설정, bundle identifier, team ID 및 provisioning profile 설정

표준 Capacitor 템플릿 외에 직접 추가한 native Swift, Objective-C, framework, extension 또는 SDK 파일도 모두 유지해야 합니다.

옵션 1: Capacitor migration assistant 사용

iOS 프로젝트에 유지하고 싶은 커스텀 네이티브 수정 사항이 있는 경우 이 경로를 사용하세요.

Capacitor 프로젝트 루트에서 어시스턴트를 실행하세요:

bunx cap spm-migration-assistant

어시스턴트는 CocoaPods 인프라를 제거하고 로컬 CapApp-SPM 패키지를 생성하며, 설치된 플러그인에서 패키지 참조를 생성하고 생성된 SPM 설정 파일을 만듭니다.

완료되면 프로젝트를 여세요:

bunx cap open ios

그 후 어시스턴트가 출력한 수동 Xcode 단계를 따르세요. 대부분의 프로젝트에서는 다음과 같습니다:

추가 CapApp-SPM 로컬 패키지 의존성으로 추가합니다.
생성된 debug.xcconfig 을(를) 앱 구성에 추가합니다.
SPM으로 변환할 수 없는 플러그인에 대한 경고가 있으면 해결하세요.
CI를 업데이트하기 전에 Xcode에서 앱을 한 번 빌드하세요.

Xcode 프로젝트가 빌드되면 다시 동기화하세요:

bunx cap sync ios

옵션 2: SPM으로 iOS 프로젝트 다시 스캐폴딩

다음 경우 이 경로를 사용하세요: ios/ 디렉터리가 기본 Capacitor 템플릿과 유사하고, 이후 커스텀 파일을 안전하게 복원할 수 있을 때.

먼저 백업 섹션에 나열된 파일이 커밋되었거나 안전한 곳에 복사되었는지 확인하세요. 그런 다음 SPM으로 iOS 프로젝트를 삭제하고 다시 생성하세요:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

앱에 필요한 네이티브 파일을 복원한 다음 프로젝트를 여세요:

bunx cap open ios

이 경로는 새 Capacitor 8 iOS 템플릿을 제공하므로 인플레이스 마이그레이션보다 종종 더 깔끔합니다. 대신 서명, entitlements, Firebase 파일, 네이티브 소스 변경 사항, 커스텀 Xcode 설정을 신중하게 다시 적용해야 합니다.

새 Capacitor 앱

새 앱에서는 Capacitor 8이 iOS를 추가할 때 기본적으로 SPM을 사용합니다:

bunx cap add ios

명시적으로 지정해야 한다면 패키지 매니저 옵션을 계속 전달할 수 있습니다:

bunx cap add ios --packagemanager SPM

마이그레이션 후 CI 업데이트

앱이 로컬에서 빌드되면 CI/CD가 더 이상 CocoaPods를 전제로 하지 않도록 업데이트하세요.

다음 단계를 실행하는 항목을 제거하세요:

pod install

다음 캐시도 제거하세요:

ios/App/Pods
ios/App/Podfile.lock
해당 앱 전용으로 캐시된 경우 CocoaPods 스펙 저장소

일반적인 웹 빌드 및 Capacitor 동기화 단계를 유지하세요. 일반적인 iOS 작업은 JavaScript 의존성 설치, 웹 자산 빌드, Capacitor 동기화, 그리고 Xcode로 빌드하는 순서여야 합니다:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

마이그레이션 체크리스트

마이그레이션 전:

새로운 git 브랜치를 생성하세요.
현재 작업 중인 앱을 커밋하세요.
모든 설치된 플러그인이 SPM을 지원하는지 확인하세요.
커스텀 iOS 파일 및 서명 설정을 기록하세요.
마이그레이션 전에 앱이 정상적으로 빌드되는지 확인하세요.

마이그레이션 중:

실행 bunx cap spm-migration-assistant 또는 재스캐폴딩 ios/.
추가 CapApp-SPM 필요한 경우 Xcode에서 진행하세요.
추가 debug.xcconfig 필요한 경우 Xcode에서 진행하세요.
앱별 네이티브 파일 복원
실행 bunx cap sync ios.

마이그레이션 후:

Xcode에서 앱 빌드 및 실행
남은 CocoaPods 파일 제거
제거 pod install CI에서
릴리스 서명이 여전히 작동하는지 확인하세요.
배포 전 시뮬레이터와 실제 기기에서 각각 한 번 이상 앱을 실행해 보세요.

문제 해결

Xcode에서 패키지를 해결하지 못하면 Xcode에서 패키지 캐시를 초기화하고 다음을 실행하세요 bunx cap sync ios 다시.

플러그인 문제로 마이그레이션이 실패했다면, 해당 플러그인에 SPM을 지원하는 새 버전이 있는지 확인하세요. 직접 관리하는 플러그인이라면 먼저 플러그인 패키지를 마이그레이션한 뒤 앱 마이그레이션으로 돌아오세요.

로컬에서는 빌드가 되지만 CI에서 실패하면, 오래된 CocoaPods 가정을 확인하세요. 흔한 원인은 강제된 .xcworkspace 빌드 경로, 오래된 pod install 명령어, 또는 이전 빌드에서 남은 Pods/ 캐시입니다.

마치며

Capacitor 앱을 Swift Package Manager로 마이그레이션하는 것은 주로 iOS 의존성 연결을 교체하는 것입니다. CapApp-SPM 의존성 참조를 담당하며, debug.xcconfig 생성된 CocoaPods 빌드 구성을 대체하고, CI에서는 더 이상 필요하지 않습니다 pod install.

커스터마이징된 iOS 프로젝트의 경우 다음으로 시작하세요 bunx cap spm-migration-assistant. 기본 템플릿에 가까운 프로젝트의 경우, 깨끗한 SPM 리스캐폴딩이 더 빠르고 이해하기 쉽습니다.

리소스

Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법부터 계속하기

사용 중이라면 Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법 마이그레이션과 엔터프라이즈 운영을 계획하려면 다음과 연결하세요: Capgo 엔터프라이즈 Capgo Enterprise의 제품 워크플로우를 위해, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우를 위해, Capgo 대안 Capgo Alternatives의 제품 워크플로우용, Capgo 컨설팅 Capgo Consulting의 제품 워크플로우용, Capgo 프리미엄 지원 Capgo Premium Support의 제품 워크플로우용.