How to Migrate Your Capacitor App to Swift Package Manager

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

이 안내서는 앱 팀을 위한 것입니다. CocoaPods에서 SPM으로 Capacitor iOS 앱을 마이그레이션하는 방법, 마이그레이션 어시스턴트가 변경하는 것, Xcode에서 확인해야 하는 것, 앱 빌드 후 CI를 정리하는 방법을 설명합니다.

앱에서 변경되는 것

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

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

Capacitor SPM 기반 앱은 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

다음으로 __CAPGO_KEEP_0__ 하위에 커스터마이즈한 것을 검토합니다.

보존해야 하는 일반 파일 및 설정은: ios/App/__CAPGO_KEEP_0__

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 통합을 제거하고, 로컬 패키지를 생성하고, 설치된 네이티브 의존성에 대한 패키지 참조를 생성하고, iOS 프로젝트에 필요한 구성 요소를 생성합니다. CapApp-SPM 완료되면 iOS 프로젝트를 열어보세요:

After it finishes, open the iOS project:

npx cap open ios

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

Xcode 단계를 완료하십시오.

Xcode에서 앱 프로젝트 및 대상 설정을 확인하십시오:

확인하십시오 CapApp-SPM 로컬 패키지 의존성으로 추가되었습니다.
앱 대상이 생성된 패키지 제품을 연결하고 있는지 확인하십시오.
어시스턴트가 추가하도록 요청하면 프로젝트 설정에 생성된 debug.xcconfig 을 추가하십시오.
Xcode에서 패키지 경고를 해결하십시오.
Xcode에서 앱을 한 번 빌드하십시오.

Xcode가 패키지를 해결할 수 없으면 File > Packages > Reset Package Caches그런 다음 패키지를 다시 해결하세요.

Sync 및 빌드하세요.

Xcode가 구성되면 터미널로 돌아가 Capacitor를 sync하세요:

npx cap sync ios

그런 다음 Xcode에서 다시 빌드하세요. 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

그런 다음 앱에 특화된 네이티브 파일과 설정을 복원하세요. 이 경로를 사용하면 SPM 프로젝트가 깨끗하게 생성되지만, Xcode 변경 사항을 잃어버릴 위험이 있습니다. 변경 사항을 먼저 목록화하지 않았다면.

새 Capacitor 앱을 만들 때 Capacitor 8은 iOS 프로젝트를 SPM으로 기본적으로 생성합니다.

npx cap add ios

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

npx cap add ios --packagemanager SPM

설정 정리

SPM 앱 빌드 후, CocoaPods 관련 설정을 지우고 로컬 스크립트 및 CI에서 지우세요.

제거해야 하는 단계는 다음과 같습니다:

pod install

또한 CocoaPods만 존재하는 캐시도 지워야 합니다:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods 스펙 저장소
CI 캐시 키 (Podfile)

이전 마이그레이션 후에 기본 CI 흐름은 자바스크립트 의존성을 설치하고 웹 앱을 빌드하고 Capacitor를 동기화하고 Xcode로 빌드해야 합니다:

npm ci
npm run build
npx cap sync ios

CI가 여전히 빌드된다면 App.xcworkspaceCI를 프로젝트 또는 워크스페이스 경로로 업데이트하세요. 마이그레이션 후에 존재하는 경로를 유지하지 마세요. 오래된 CI가 사용한 경로만 때문입니다.

문제 해결

페이지/영역: 지원 / 프리미엄 지원 페이지 또는 푸터 지원 섹션. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (지원 정책 문제 해결 제목).

어시스턴트가 호환되지 않는 의존성을 경고한다면

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

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

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

지나친 CocoaPods 가정: pod install, Pods/ 캐시 Podfile.lock 캐시 키 .xcworkspace.

삭제된 프로젝트로 지시하는 빌드 명령어를 찾으세요.

인증서나 권한이 변경되었습니다.

이전 프로젝트와 이전 Xcode 대상 간의 차이를 비교하세요. Bundle ID, 팀, 프로비전 프로파일, 권한 파일, 기능, 확장 설정을 복원하세요.

이동 체크리스트입니다. 이전에 이체하기 전에:

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

이동 중:

Run npx cap spm-migration-assistant.
Xcode에서 프로젝트를 열어보세요. npx cap open ios.
Xcode에서 추가하세요. CapApp-SPM Xcode에서 추가하세요.
__CAPGO_KEEP_0__ debug.xcconfig __CAPGO_KEEP_1__
패키지 경고를 해결하세요.
실행 npx cap sync ios.

이동 후:

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

Capgo Skills을 사용하여 이민을 진행하세요.

AI agent를 사용하여 이민을 처리하는 경우 __CAPGO_KEEP_0__ Skills에서 시작하세요. Capgo Skills __CAPGO_KEEP_0__

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

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

결론

Swift Package Manager로 Capacitor 앱을 마이그레이션하는 것은 주로 iOS 종속성 관리 변경입니다. 가장 안전한 경로는 clean branch에서 시작하여 npx cap spm-migration-assistant마무리 단계를 완료하고 다시 싱크하고, 앱 빌드 후 CI에서 CocoaPods만 제거해야 합니다.

iOS 프로젝트가 heavly 커스텀화되어 있다면, place에서 마이그레이션하고, default Capacitor 템플릿과 가깝다면, 다시 ios/ with npx cap add ios --packagemanager SPM 생성하는 것이 더 깨끗할 수 있습니다.

Capacitor 앱을 Swift Package Manager로 이전하는 방법