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

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은 로컬 패키지 이름을 생성하고 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, 및 배포 프로파일
앱 확장, 네이티브 스위프트 파일, Objective-C 파일, 또는 임베디드 프레임워크

또한 설치된 Capacitor 및 Cordova 의존성을 확인하세요. 앱 수준 SPM 이민이 네이티브 의존성에 의해 막힐 수 있습니다. SPM 호환 경로가 없는 의존성이 있다면 가능하다면 이민하기 전에 패키지를 업데이트하세요.

이민 도우미를 사용하세요

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

npx cap spm-migration-assistant

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

터미널을 닫기 전에 어시스턴트 출력을 읽어보세요. 만약 Xcode 단계를 완료해야 한다고 말한다면, 다시 싱크하기 전에 그 단계를 완료하세요.

npx cap open ios

Xcode 단계를 완료하세요

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

확인

로컬 패키지 의존성으로 추가됩니다. CapApp-SPM 앱 대상이 생성된 패키지 제품에 링크되어 있는지 확인하세요.
생성된 __CAPGO_KEEP_0__을 프로젝트 구성에 추가하세요. 어시스턴트가 추가를 요청한다면.
__CAPGO_KEEP_0__ debug.xcconfig __CAPGO_KEEP_0__
Xcode에서 패키지 경고를 해결하세요.
Xcode에서 앱을 한 번 빌드하세요.

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

다시 싱크하고 빌드하세요.

Xcode가 설정되면 터미널로 돌아가 Capacitor:를 싱크하세요.

npx cap sync ios

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

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

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

__CAPGO_KEEP_0__ 기본 템플릿과 비슷한 폴더가 있다면, 마이그레이션을 원위치에서 진행하는 대신 SPM으로 다시 생성하는 것이 더 빠를 수 있습니다. ios/ Capacitor

이 경로를 사용하려면 모든 원시 파일과 서명 설정을 백업하거나 커밋해야 합니다.

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

그런 다음 앱에 특화된 원시 파일과 설정을 복원하세요. 이 경로는 깨끗한 SPM 프로젝트를 제공하지만 Xcode 변경을 커스텀으로 사용하지 않은 경우 custom Xcode 변경을 잃을 위험이 있습니다.

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

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 스펙 저장소
Podfile에 의존하는 CI 캐시 키

이동 후 기본 CI 흐름은 자바스크립트 의존성을 설치하고 웹 앱을 빌드하고 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.

__CAPGO_KEEP_0__이 변경되었습니다.

이전 프로젝트와 이주된 Xcode 대상의 이주된 프로젝트를 비교합니다. 번들 식별자, 팀, 배포 프로파일, 권한 파일, 기능, 확장 설정을 복원합니다.

이주 체크리스트

이주 전:

브랜치를 생성합니다.
현재 iOS 앱이 빌드되는지 확인합니다.
작업 상태를 커밋합니다.
커스텀 네이티브 파일 및 서명 설정을 인벤토리합니다.
이미 새로운 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 기술을 이관 작업에 사용하세요.

__CAPGO_KEEP_0__ 기술을 사용하여 이관 작업을 시작하세요. Capgo 기술 이관 작업을 위해 가장 유용한 기술은 다음과 같습니다.

capacitor-best-practices 앱 구조를 변경하기 전에 앱 구조를 검토하세요. ios/.
cocoapods-to-spm SPM 이관 및 Xcode 후속 조치 계획을 검토하세요.
capacitor-ci-cd CocoaPods 의존성을 빌드 PIPELINE에서 제거하세요.
debugging-capacitor 이관 작업 후 기기 전용 문제를 조사하세요. ios-android-logs 이관 작업 전에 iOS 프로젝트를 변경하기 전에 agent가 네이티브 파일, CI, 의존성 호환성을 검사할 수 있도록 사용하세요.

결론

__CAPGO_KEEP_0__ 앱을 Swift Package Manager로 이관하는 것은 주로 iOS 의존성 관리 변경입니다. 가장 안전한 경로는 clean branch에서 시작하여

Capacitor npx cap spm-migration-assistantiOS 프로젝트가 heavly 커스텀화되어 있다면, __CAPGO_KEEP_0__ 내부에서 마이그레이션을 진행하십시오. __CAPGO_KEEP_0__ 기본 템플릿과 유사한 경우, 다시 생성하는 것이 더 깨끗할 수 있습니다.

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ __CAPGO_KEEP_0__ Swift Package Manager 문서 npx cap add ios --packagemanager SPM __CAPGO_KEEP_0__ 8 업데이트 가이드

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