How to Migrate Your Capacitor App to Swift Package Manager

Capacitor iOS 프로젝트의 기본 방향은 Swift Package Manager입니다. 앱이 여전히 CocoaPods를 사용한다면, JavaScript code, Android 프로젝트, 또는 릴리즈 워크플로를 다시 만들지 않고도 앱을 SPM으로 이전할 수 있습니다.

This guide is for app teams. It explains how to migrate a Capacitor iOS app from CocoaPods to SPM, what the migration assistant changes, what you still need to check in Xcode, and how to clean up CI after the app builds.

앱에서 변경되는 것

Capacitor CocoaPods 기반 앱은 파일들에 의존합니다:

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

SPM 기반 Capacitor 앱은 iOS 의존성 연결을 Swift Package Manager로 이동시킵니다. 이중 Capacitor은 로컬 패키지 이름을 생성하고 CapApp-SPM 그리고 Capacitor과 설치된 네이티브 의존성을 연결하기 위해 사용합니다.

웹 빌드는 여전히 동일하게 작동합니다. 웹 빌드를 실행하고 Capacitor을 동기화하고 Xcode를 열고 앱을 압축하는 방식은 여전히 동일합니다. 주요 차이점은 CocoaPods가 iOS 의존성 그래프를 더 이상 소유하지 않기 때문입니다.

이전으로 돌아가기 전에

새로운 branch에서 시작하고 현재 앱이 빌드되는지 확인한 후 의존성 관리자를 변경하기 전에:

git status
npm run build
npx cap sync ios

그런 다음 작업 중인 상태를 커밋합니다. 이중 이스케이프 iOS 프로젝트 파일을 생성하기 때문에 rollback 지점이 깨끗해야 합니다.

다음으로, 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를 사용한다면
custom .xcconfig 파일
인증 설정, 번들 식별자, 팀 ID, 및 배포 프로파일
앱 확장, 네이티브 Swift 파일, Objective-C 파일, 또는 임베디드 프레임워크

설치된 Capacitor 및 Cordova 의존성을 확인하세요. 앱 수준 SPM 마이그레이션은 SPM 호환 경로가 없는 네이티브 의존성에 의해 차단될 수 있습니다. 가능하다면 마이그레이션 전에 업데이트하십시오.

마이그레이션 어시스턴트를 사용하세요

대부분의 기존 앱의 경우, 공식 Capacitor 마이그레이션 어시스턴트에서 시작하세요:

npx cap spm-migration-assistant

Capacitor 프로젝트의 루트에서 어시스턴트를 실행하세요. 어시스턴트는 CocoaPods 통합을 제거하고, 로컬 패키지를 생성하고, 설치된 네이티브 의존성에 대한 패키지 참조를 생성하고, iOS 프로젝트에 필요한 생성된 구성 추가합니다. CapApp-SPM 어시스턴트가 완료되면 iOS 프로젝트를 열어보세요:

터미널을 닫기 전에 어시스턴트 출력을 읽으세요. 어시스턴트가 수동 Xcode 단계를 완료하도록 요청하면, 다시 싱크하기 전에 그 단계를 완료하세요.

npx cap open ios

Xcode 단계를 완료하세요

Xcode에서 앱 프로젝트 및 대상 구성 확인:

확인하세요

확인 CapApp-SPM 로컬 패키지 종속성으로 추가됩니다.
앱 목표가 생성된 패키지 제품과 연결되어 있는지 확인합니다.
생성된 debug.xcconfig 프로젝트 구성에 생성된
Xcode에서 패키지 경고를 해결합니다.
Xcode에서 앱을 한 번 빌드합니다.

Xcode가 패키지를 해결할 수 없다면 "File > Packages > Reset Package Caches"를 사용하세요. 패키지 캐시를 다시 초기화한 후 패키지를 다시 해결하세요.Xcode가 구성되면 터미널로 돌아가 __CAPGO_KEEP_0__:를 동기화하세요.

다시 Xcode에서 빌드하세요. Xcode에서 깨끗한 빌드가 작동할 때까지 마이그레이션을 완료한 것으로 간주하지 마세요. 왜냐하면 릴리스 서명, 특권, 앱 확장, 패키지 해결은 Xcode에서 검증됩니다.

Xcode에서 빌드가 성공적으로 완료되면 터미널로 돌아가 Capacitor:를 다시 동기화하세요.

npx cap sync ios

마지막으로 Xcode에서 빌드하세요.

If the app uses push notifications, associated domains, background modes, app groups, Firebase, or any native SDK configuration, run those flows on a simulator or device after the build succeeds.

iOS를 SPM으로 다시 생성하는 대안

If your ios/ folder is close to the default Capacitor template, it can be faster to recreate it with SPM instead of migrating in place.

Only use this path after committing or backing up every native file and signing setting you need:

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

그런 다음 앱에 특화된 네이티브 파일과 설정을 복원하세요. 이 경로에서는 SPM 프로젝트를 깨끗하게 만듭니다. 그러나 Xcode 변경 사항을 잃어버릴 위험이 더 높아집니다. 만약 변경 사항을 먼저 목록화하지 않았다면.

For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

npx cap add ios

SPM으로 iOS 프로젝트를 생성할 수 있습니다.

npx cap add ios --packagemanager SPM

Clean up CocoaPods leftovers

CocoaPods의 남은 것들을 정리하세요.

After the SPM app builds, remove leftover CocoaPods assumptions from local scripts and CI.

pod install

SPM 앱이 빌드된 후, 로컬 스크립트와 CI에서 CocoaPods의 남은 가정들을 삭제하세요. 예를 들어, 다음과 같은 단계를 삭제하세요:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods specs 저장소
CI 캐시 키는 Podfile에 따라 생성됩니다.

Capgo 이주 후 기본 CI 흐름은 JavaScript 의존성을 설치하고 웹 앱을 빌드하고 Capacitor을 동기화하고 Xcode로 빌드해야 합니다.

npm ci
npm run build
npx cap sync ios

CI가 여전히 빌드한다면 App.xcworkspace업데이트하여 프로젝트 또는 워크스페이스 경로로 업데이트하세요. Capgo 이주 후에도 오래된 CocoaPods 경로를 유지하지 마십시오. 오래된 작업이 사용한 것만으로도.

문제 해결

어시스턴트는 호환되지 않는 의존성을 경고합니다.

의존성을 먼저 업데이트하고 어시스턴트를 다시 실행하세요. SPM 호환 버전이 없다면, 유지보수자가 SPM 지원을 추가하거나 의존성을 교체할 때까지 앱을 CocoaPods에서 유지하세요.

Xcode가 패키지를 해결할 수 없습니다.

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

The app builds locally but CI fails

CI에서 실패하는 앱은 로컬에서 빌드가 되는지 확인하세요. pod install, Pods/ cache keys, Podfile.lock caches, .xcworkspace.

cache keys,

caches,

cache keys,

caches,

Signing or entitlements changed
이전 프로젝트와 migrated Xcode target을 비교하세요. Bundle identifier, team, provisioning profile, entitlements file, capabilities, extension settings을 원래대로 복원하세요.
Migration checklist
이전 프로젝트 전환 전:
최신 SPM 호환 버전이 이미 출시된 원본 종속성을 업데이트하십시오.

이동 중:

실행 npx cap spm-migration-assistant.
__CAPGO_KEEP_0__ 프로젝트를 열어보십시오. npx cap open ios.
Xcode에서 필요 시 추가 CapApp-SPM Xcode에서 필요 시 추가
패키지 경고를 해결하십시오. debug.xcconfig 실행
이동 후:
Xcode에서 앱을 빌드하십시오. npx cap sync ios.

Xcode에서 필요 시 추가

Xcode에서 필요 시 추가
__CAPGO_KEEP_0__ 기능을 시뮬레이터 또는 기기에서 테스트합니다.
CI에서 CocoaPods 명령어를 제거합니다.
CocoaPods 전용 캐시를 제거합니다.
아카이브 및 릴리스 서명 확인합니다.

Capgo 기능을 이주 작업에 사용합니다.

AI agent를 사용하여 이주 작업을 처리한다면 Capgo 기능 비어있는 프롬프트 대신에 시작합니다. 이 작업에 가장 유용한 기능은 다음과 같습니다.

capacitor-best-practices 앱 구조를 변경하기 전에 ios/.
cocoapods-to-spm SPM 이주 및 Xcode 후속 작업을 계획합니다.
capacitor-ci-cd 빌드 PIPELINE에서 CocoaPods 가정치를 제거합니다.
debugging-capacitor 그리고 ios-android-logs 이전 장치 전용 문제를 해결하기 위해 마이그레이션 후 조사합니다.

iOS 프로젝트를 변경하기 전에 사용하여 에이전트가 네이티브 파일, CI, 종속성 호환성을 감사하는 대신 마이그레이션 명령만 실행하는 대신에.

결론

Capacitor 앱을 Swift Package Manager로 마이그레이팅하는 것은 주로 iOS 종속성 관리 변경입니다. 가장 안전한 경로는 clean branch에서 시작하여 npx cap spm-migration-assistant, 수동 Xcode 단계를 완료하고 다시 동기화하고 CI에서만 CocoaPods를 제거하기 전에 앱이 빌드되도록합니다.

iOS 프로젝트가 heavly 커스텀화되어 있다면, 마이그레이션을 원위치에서 수행하십시오. 만약 기본 Capacitor 템플릿과 가깝다면, 재생성 ios/ with npx cap add ios --packagemanager SPM 가 더 깨끗합니다.