Capacitor 앱을 스위프트 패키지 매니저로 마이그레이션하는 방법

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

이 안내서는 앱 팀을 위한 것입니다. CocoaPods에서 SPM으로 Capacitor iOS 앱을 이전하는 방법, 이전 도우미가 변경하는 내용, 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을 사용하여 Capacitor과 설치된 네이티브 의존성을 연결하는 데 사용되는 로컬 패키지를 생성합니다. CapApp-SPM 웹 빌드는 여전히 동일하게 작동합니다. 웹 빌드를 실행하고 Capacitor을 동기화하고 Xcode를 열고 앱을 아카이브합니다. 주요 차이점은 CocoaPods가 iOS 의존성 그래프를 더 이상 소유하지 않는다는 것입니다.

The web build still works the same way. You still run a web build, sync Capacitor, open Xcode, and archive the app. The main difference is that CocoaPods no longer owns the iOS dependency graph.

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

그런 다음 작업 상태를 커밋합니다. 이전 도우미는 생성된 iOS 프로젝트 파일을 수정하므로 rollback 지점을 정리하는 것이 중요합니다.

git status
npm run build
npx cap sync ios

Editor

다음으로, 앱에서 __CAPGO_KEEP_0__로 커스터마이즈 한 항목을 검토하세요. 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 파일
인증 설정, 번들 식별자, 팀 ID, 및 배포 프로파일
앱 확장, 네이티브 스위프트 파일, Objective-C 파일, 또는 임베디드 프레임워크

또한 설치된 Capacitor 및 Cordova 의존성을 확인하세요. 앱 수준의 SPM 마이그레이션은 SPM 호환 경로가 없는 네이티브 의존성으로 차단될 수 있습니다. 가능할 때 마이그레이션 전에 업데이트한 패키지를 마이그레이션할 수 있습니다.

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

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

npx cap spm-migration-assistant

어시스턴트를 루트 디렉토리에서 Capacitor 프로젝트에서 실행하세요. 어시스턴트는 CocoaPods 통합을 제거하고, 지역 CapApp-SPM 패키지, 설치된 네이티브 의존성을 위한 패키지 참조를 생성하고 iOS 프로젝트에 필요로 하는 생성된 구성이 필요합니다.

완료되면 iOS 프로젝트를 열어 주세요.

npx cap open ios

터미널을 닫기 전에 어시스턴트 출력을 읽어 주세요. 어시스턴트가 다시 싱크하기 전에 수동으로 Xcode 단계를 완료하라고 요청하는 경우, 그 단계를 완료하세요.

Xcode 단계를 완료하세요.

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

확인 CapApp-SPM Capacitor가 로컬 패키지 의존성으로 추가됩니다.
제네레이티드 패키지 제품을 앱 대상과 연결합니다.
제네레이티드 패키지를 프로젝트 구성에 추가하도록 어시스턴트가 요청하는 경우, 그 요청에 따라 추가하세요. debug.xcconfig Xcode에서 패키지 경고를 해결하세요.
Xcode에서 앱을 한 번 빌드하세요.
Build the app once from Xcode.

Xcode가 패키지를 해결할 수 없다면 사용하세요 파일 > 패키지 > 패키지 캐시 초기화, 그 다음 패키지를 다시 해결하세요.

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

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

npx cap sync ios

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

앱이 푸시 알림, 연관된 도메인, 배경 모드, 앱 그룹, Firebase, 또는 네이티브 SDK 설정을 사용한다면 빌드가 성공한 후 시뮬레이터 또는 기기에서 해당 흐름을 실행하세요.

대안: iOS를 SPM으로 다시 생성하세요

만약 ios/ 디렉토리가 기본 Capacitor 템플릿과 비슷하다면, 마이그레이션을 원위치하는 것보다 SPM으로 다시 생성하는 것이 더 빠를 수 있습니다.

만약

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

디렉토리가 기본 __CAPGO_KEEP_0__ 템플릿과 비슷하다면, 마이그레이션을 원위치하는 것보다 SPM으로 다시 생성하는 것이 더 빠를 수 있습니다. 하지만 native 파일과 서명 설정을 모두 백업하거나 커밋한 후에만 이 경로를 사용하세요:

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

npx cap add ios

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

npx cap add ios --packagemanager SPM

CocoaPods의 잔여물 청소

SPM 앱 빌드 후, CocoaPods의 가정에서 지역 스크립트 및 CI에서 지우십시오.

다음과 같은 단계를 제거하십시오:

pod install

또한 CocoaPods에만 존재했던 캐시를 제거하십시오:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods spec 저장소
CI 캐시 키가 Podfile에 기반한 것

A basic CI flow after migration should install JavaScript dependencies, build the web app, sync Capacitor, and build with Xcode:

npm ci
npm run build
npx cap sync ios

CI가 여전히 빌드한다면 App.xcworkspaceCI를 프로젝트 또는 워크스페이스 경로로 업데이트하십시오. 이주 후에 존재하는 경로를 그대로 유지하지 마십시오.

문제 해결

의존성 관리 도우미가 호환되지 않는 의존성을 경고합니다.

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

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

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

앱이 로컬에서 빌드되지만 CI가 실패합니다.

CocoaPods의 오래된 가정: pod install, Pods/ 캐시 Podfile.lock 캐시 키 .xcworkspace.

또는 삭제된

로 지시하는 빌드 명령을 찾으세요. 서명 또는 권한이 변경되었습니다.

이동 체크리스트

이동 전:

Branch를 생성하세요.
현재 iOS 앱 빌드를 확인하세요.
작업 중인 상태를 커밋하세요.
사용자 정의 네이티브 파일 및 서명 설정을 확인하세요.
이미 SPM 호환 버전이 있는 네이티브 의존성을 업데이트하세요.

이동 중:

실행 npx cap spm-migration-assistant.
Xcode에서 프로젝트를 열어 npx cap open ios.
필요한 경우에만 CapApp-SPM protectedTokens
추가 debug.xcconfig Xcode에서 필요 시 추가합니다.
패키지 경고를 해결합니다.
실행 npx cap sync ios.

이동 후:

Xcode에서 앱을 빌드합니다.
시뮬레이터 또는 장치에서 네이티브 기능을 테스트합니다.
CI에서 CocoaPods 명령어를 제거합니다.
CocoaPods 전용 캐시를 제거합니다.
아카이브 및 릴리스 서명 확인합니다.

Capgo 기술을 사용하여 마이그레이션을 수행합니다.

AI agent를 사용하여 마이그레이션을 처리하는 경우 시작점으로 Capgo 기술 대신 빈 프롬프트 대신. 이 작업에 가장 유용한 기술은:

capacitor-best-practices 앱 구조를 변경하기 전에 리뷰 ios/.
cocoapods-to-spm SPM 마이그레이션 및 Xcode 후속 단계를 계획
capacitor-ci-cd CocoaPods 의존성을 제거
debugging-capacitor 그리고 ios-android-logs 마이그레이션 후 장치 전용 문제를 조사

이러한 명령을 실행하기 전에 iOS 프로젝트를 변경하기 전에 agent가 네이티브 파일, CI 및 종속성 호환성을 감사하는 대신

결론

Swift Package Manager로 Capacitor 앱을 마이그레이션하는 것은 주로 iOS 의존성 관리 변경입니다. 가장 안전한 경로는 clean branch에서 시작하여 npx cap spm-migration-assistant마지막으로 CI에서 CocoaPods를 제거하고 앱이 빌드되면

iOS 프로젝트가 커스터마이즈가 많이 된 경우에는 원위치 마이그레이션을, 기본 Capacitor 템플릿과 가깝다면 다시 생성 ios/ with npx cap add ios --packagemanager SPM can be cleaner.