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

Swift Package Manager는 Capacitor iOS 프로젝트의 기본 방향입니다. 앱이 여전히 CocoaPods를 사용 중이더라도, JavaScript code이나 Android 프로젝트, 또는 릴리스 워크플로우를 처음부터 다시 구축할 필요 없이 앱 자체를 SPM으로 마이그레이션할 수 있습니다.

이 가이드는 앱 개발 팀을 위한 것입니다. Capacitor iOS 앱을 CocoaPods에서 SPM으로 마이그레이션하는 방법, 마이그레이션 어시스턴트가 변경하는 사항, Xcode에서 여전히 확인해야 할 부분, 그리고 앱 빌드 후 CI를 정리하는 방법을 설명합니다.

앱 내 변경 사항

CocoaPods 기반의 Capacitor 앱은 다음과 같은 파일에 의존합니다:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

SPM 기반 Capacitor 앱은 iOS 의존성 연결 방식을 Swift Package Manager로 전환합니다. 마이그레이션 과정에서 Capacitor은 다음 이름의 로컬 패키지를 생성합니다. CapApp-SPM 또한 이를 사용하여 앱 타겟을 Capacitor 및 설치된 native dependencies와 연결합니다.

웹 빌드 방식은 이전과 동일합니다. 기존처럼 웹 빌드를 실행하고, Capacitor을 sync한 뒤, Xcode를 열어 앱을 archive하면 됩니다. 가장 큰 차이점은 CocoaPods가 더 이상 iOS 의존성 그래프를 관리하지 않는다는 점입니다.

마이그레이션 전 주의사항

의존성 관리자를 변경하기 전에, 깨끗한 브랜치에서 시작하여 현재 앱이 정상적으로 빌드되는지 확인하세요:

git status
npm run build
npx cap sync ios

그 다음 현재 상태를 commit하세요. 마이그레이션 시 생성된 iOS 프로젝트 파일들이 수정되므로, 깨끗한 롤백 지점을 확보하는 것이 중요합니다.

다음으로, 앱에서 다음 항목 아래에 설정한 커스텀 사항들을 검토하세요. 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 settings, bundle identifier, team ID, provisioning profiles
app extensions, native Swift files, Objective-C files, 또는 embedded frameworks

설치된 Capacitor 및 Cordova 의존성도 확인하세요. SPM을 지원하지 않는 native dependency가 있으면 앱 레벨의 SPM 마이그레이션이 차단될 수 있습니다. 가능한 경우 마이그레이션 전에 해당 패키지들을 업데이트하세요.

migration assistant 사용하기

대부분의 기존 앱은 공식 Capacitor migration assistant로 시작하세요:

npx cap spm-migration-assistant

Capacitor 프로젝트 루트에서 실행하세요. assistant는 CocoaPods 통합을 제거하고 로컬 CapApp-SPM package를 생성하며, 설치된 native dependency를 위한 package reference를 생성하고 iOS 프로젝트에 필요한 구성 파일을 추가합니다.

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

npx cap open ios

터미널을 닫기 전에 assistant 출력 내용을 확인하세요. 수동 Xcode 작업이 필요하다는 메시지가 뜨면, 다시 sync하기 전에 해당 작업을 완료해야 합니다.

Xcode 작업 마무리하기

Xcode에서 app project 및 target 구성을 확인하세요:

확인 CapApp-SPM 가 로컬 패키지 의존성으로 추가됩니다.
앱 타겟이 생성된 패키지 제품을 연결하는지 확인하세요.
생성된 debug.xcconfig 를 어시스턴트가 요청하면 프로젝트 설정에 추가하세요.
Xcode에서 패키지 경고를 모두 해결하세요.
Xcode에서 앱을 한 번 빌드하세요.

Xcode가 패키지를 해결하지 못하면 파일 > Packages > Reset Package Caches를 선택한 후 패키지를 다시 해결하세요.

다시 동기화하고 빌드하세요

Xcode 설정이 완료되면 터미널로 돌아가 Capacitor를 동기화하세요:

npx cap sync ios

그 다음 Xcode에서 다시 빌드하세요. 릴리스 서명, entitlements, app extensions 및 패키지 해결이 Xcode에서 검증되므로, Xcode에서 클린 빌드가 성공하기 전까지는 마이그레이션이 완료된 것으로 간주하지 마세요.

앱에서 푸시 알림, associated domains, background modes, app groups, Firebase 또는 기타 네이티브 SDK 설정을 사용하는 경우, 빌드 성공 후 시뮬레이터나 기기에서 해당 기능들을 실행해 보세요.

대안: SPM으로 iOS 프로젝트 재생성

만약 ios/ 폴더가 기본 Capacitor 템플릿과 유사하다면, 기존 프로젝트를 마이그레이션하는 대신 SPM으로 새로 만드는 것이 더 빠를 수 있습니다.

모든 네이티브 파일과 서명 설정을 커밋하거나 백업한 후에만 이 방법을 사용하세요:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

그 다음 앱 전용 네이티브 파일과 설정을 복구하세요. 이 방식은 깨끗한 SPM 프로젝트를 제공하지만, 사전에 목록을 만들어두지 않으면 커스텀 Xcode 변경 사항을 잃어버리기 쉽습니다.

새로운 Capacitor 앱의 경우, Capacitor 8은 기본적으로 SPM을 사용하여 iOS 프로젝트를 생성합니다:

npx cap add ios

명시적으로 지정할 수도 있습니다:

npx cap add ios --packagemanager SPM

CocoaPods 잔재 정리하기

SPM 앱 빌드가 완료되면, 로컬 스크립트와 CI에서 CocoaPods를 전제로 했던 설정들을 제거하세요.

다음과 같은 단계들을 제거하세요:

pod install

CocoaPods 전용으로 존재했던 캐시도 함께 제거하세요:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs repository
Podfile 기반의 CI 캐시 키

마이그레이션 후 기본적인 CI 흐름은 JavaScript 의존성 설치, 웹 앱 빌드, Capacitor 동기화, 그리고 Xcode 빌드 순으로 진행되어야 합니다:

npm ci
npm run build
npx cap sync ios

CI 빌드가 여전히 실패한다면 App.xcworkspace마이그레이션 후 생성된 프로젝트 또는 워크스페이스 경로로 업데이트하세요. 이전 작업에서 사용했다는 이유로 오래된 CocoaPods 경로를 그대로 두면 안 됩니다.

문제 해결

어시스턴트가 호환되지 않는 의존성에 대해 경고합니다

의존성을 먼저 업데이트한 후 어시스턴트를 다시 실행하세요. SPM 호환 버전이 없다면, 해당 의존성을 교체하거나 유지 관리자가 SPM 지원을 추가할 때까지 CocoaPods를 계속 사용해야 합니다.

Xcode에서 패키지를 해결할 수 없습니다

Xcode에서 패키지 캐시를 초기화하고, CapApp-SPM 이(가) 로컬 패키지로 존재하는지 확인한 후 실행하세요 npx cap sync ios 다시.

로컬 빌드는 성공하지만 CI에서 실패하는 경우

오래된 CocoaPods 가정을 찾아보세요: pod install, Pods/ 캐시, Podfile.lock 캐시 키, 또는 삭제된 경로를 가리키는 빌드 명령 .xcworkspace.

Signing 또는 entitlements 변경됨

마이그레이션된 Xcode target을 이전 프로젝트와 비교하세요. bundle identifier, team, provisioning profile, entitlements file, capabilities 및 extension 설정을 복원하세요.

마이그레이션 체크리스트

마이그레이션 전:

새 브랜치를 생성하세요.
현재 iOS 앱 빌드가 정상인지 확인하세요.
정상 작동하는 상태를 커밋하세요.
커스텀 네이티브 파일과 signing 설정을 파악하세요.
이미 SPM 호환 최신 버전이 출시된 네이티브 의존성을 업데이트하세요.

마이그레이션 과정:

실행 npx cap spm-migration-assistant.
다음 도구로 프로젝트를 여세요: npx cap open ios.
추가 CapApp-SPM 필요한 경우 Xcode에서 실행하세요.
추가 debug.xcconfig 필요한 경우 Xcode에서 실행하세요.
패키지 경고를 해결하세요.
실행 npx cap sync ios.

마이그레이션 완료 후:

Xcode에서 앱을 빌드하세요.
시뮬레이터나 기기에서 네이티브 기능을 테스트하세요.
CI에서 CocoaPods 명령어를 제거하세요.
CocoaPods 전용 캐시를 삭제하세요.
아카이브 및 릴리스 서명을 확인하세요.

마이그레이션에 Capgo Skills를 활용하세요

AI 에이전트로 마이그레이션을 진행한다면, 빈 프롬프트 대신 Capgo 기술 스택 다음의 스킬부터 시작하는 것이 좋습니다. 이 작업에 가장 유용한 스킬은 다음과 같습니다:

capacitor-best-practices 변경 전 앱 구조를 검토하는 스킬 ios/.
cocoapods-to-spm SPM 마이그레이션 및 Xcode 후속 단계를 계획하는 스킬
capacitor-ci-cd 빌드 파이프라인에서 CocoaPods 의존성을 제거하는 스킬
debugging-capacitor 및 ios-android-logs 마이그레이션 후 특정 기기에서만 발생하는 문제를 조사하기 위해.

단순히 마이그레이션 명령만 실행하는 대신, 에이전트가 네이티브 파일, CI 및 의존성 호환성을 검사할 수 있도록 iOS 프로젝트를 변경하기 전에 사용하세요.

마치며

Capacitor 앱을 Swift Package Manager로 마이그레이션하는 것은 주로 iOS 의존성 관리 방식을 변경하는 작업입니다. 가장 안전한 방법은 깨끗한 브랜치에서 시작하여 다음을 실행하는 것입니다. npx cap spm-migration-assistant, 수동 Xcode 단계를 완료한 후 다시 sync하고, 앱 빌드가 성공한 것을 확인한 뒤에만 CI에서 CocoaPods를 제거하세요.

iOS 프로젝트가 많이 커스텀된 상태라면 기존 프로젝트에서 마이그레이션을 진행하세요. 만약 기본 Capacitor 템플릿에 가깝다면, 새로 생성하는 것이 ios/ 포함 npx cap add ios --packagemanager SPM 더 깔끔할 수 있습니다.