Capacitor 앱을 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.

앱에서 변경되는 것

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 의존성 그래프를 더 이상 소유하지 않습니다.

이전의 의존성 관리자로 이주하기 전에

clean branch에서 시작하고 현재 앱이 빌드되기 전에 의존성 관리자를 변경하지 마십시오.

git status
npm run build
npx cap sync ios

그런 다음 작업 상태를 커밋하십시오. 이주가 생성된 iOS 프로젝트 파일을 수정하므로 rollback할 수 있는 clean한 상태가 중요합니다.

다음으로, __CAPGO_KEEP_1__에서 사용자 지정한 항목을 검토하십시오. 일반적인 파일 및 설정을 보존해야 하는 항목은: ios/App/, 만 존재하는 경우

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, 만 Firebase를 사용하는 경우
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist사용자 지정
파일 .xcconfig __CAPGO_KEEP_0__
인증 설정, 번들 식별자, 팀 ID, 및 배포 프로파일
앱 확장, 네이티브 Swift 파일, Objective-C 파일, 또는 임베디드 프레임워크

설치된 Capacitor 및 Cordova 의존성을 확인하세요. 앱 수준 SPM 이주가 네이티브 의존성에 의해 차단될 수 있습니다. 가능하다면 업데이트하기 전에 의존성을 업데이트하세요.

이주 도우미를 사용하세요

대부분의 기존 앱의 경우, 공식 Capacitor 이주 도우미를 시작하세요:

npx cap spm-migration-assistant

Run it from the root of your Capacitor project. The assistant removes CocoaPods integration, creates the local CapApp-SPM 완료되면 iOS 프로젝트를 열어보세요:

터미널을 닫기 전에 도우미 출력을 읽으세요. 만약 완료 후 수동 Xcode 단계를 요청한다면, 그 단계를 완료하세요.

npx cap open ios

Xcode 단계를 완료하세요

Xcode에서 앱 프로젝트 및 대상 구성 설정을 확인하세요:

확인하세요

Confirm CapApp-SPM local package dependency로 추가됩니다.
앱 목표가 생성된 패키지 제품과 연결되어 있는지 확인합니다.
생성된 debug.xcconfig assistant가 추가를 요청하면 프로젝트 구성에
Xcode에서 패키지 경고를 해결합니다.
Xcode에서 앱을 한 번 빌드합니다.

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

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

After Xcode is configured, return to the terminal and sync 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/ 폴더가 기본 Capacitor 템플릿과 비슷하다면, 재생성하는 대신에 원장 내에서 마이그레이션하는 것이 더 빠를 수 있습니다.

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 변경 사항을 잃어버릴 위험이 있습니다. 사용자 지정 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의 잔여물이 있는 로컬 스크립트와 CI에서 제거하세요.

Remove steps like:

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이주 후 프로젝트 또는 워크스페이스 경로로 업데이트하세요. 오래된 CI가 사용한 CocoaPods 경로를 그냥 남겨두지 마세요.

문제 해결

어시스턴트는 불일치하는 의존성을 경고합니다.

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

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

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

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

구의 CocoaPods 가정들을 찾으세요: pod install, Pods/ 캐시, Podfile.lock 캐시 키, .xcworkspace.

빌드 명령어에 삭제된

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

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

이주 체크리스트

이주 전:
브랜치를 생성하세요.
현재 iOS 앱이 빌드되는지 확인하세요.
작업 상태를 커밋하세요.
__CAPGO_KEEP_0__을 최신 SPM 호환 버전으로 업데이트합니다.

이동 중:

__CAPGO_KEEP_0__ npx cap spm-migration-assistant.
__CAPGO_KEEP_1__ 프로젝트를 열어 npx cap open ios.
__CAPGO_KEEP_2__에서 필요 시. CapApp-SPM __CAPGO_KEEP_2__에서 필요 시.
__CAPGO_KEEP_3__ 경고를 해결합니다. debug.xcconfig __CAPGO_KEEP_0__
이동 후:
__CAPGO_KEEP_1__에서 앱을 빌드합니다. npx cap sync ios.

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__
__CAPGO_KEEP_0__ simulator 또는 기기를 사용하여 네이티브 기능을 테스트합니다.
CI에서 CocoaPods 명령어를 제거합니다.
CocoaPods 전용 캐시를 제거합니다.
아카이브 및 릴리스 서명 확인합니다.

Capgo Skills을 사용하여 마이그레이션을 진행합니다.

AI agent를 사용하여 마이그레이션을 처리할 경우 __CAPGO_KEEP_0__ Skills에서 시작하세요. 이 작업에 가장 유용한 스킬은 다음과 같습니다. Capgo Skills SPM 마이그레이션 및 Xcode 후속 작업을 계획하는 스킬을 사용합니다.

capacitor-best-practices 빌드 PIPELINE에서 CocoaPods 가정치를 제거하는 스킬을 사용합니다. ios/.
cocoapods-to-spm __CAPGO_KEEP_0__ Skills이란?
capacitor-ci-cd __CAPGO_KEEP_0__ Skills은?
debugging-capacitor __CAPGO_KEEP_0__ Skills이란? ios-android-logs __CAPGO_KEEP_0__을 대상으로 하는 장치 전용 문제를 해결하기 위해 마이그레이션 후 조사합니다.

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

결론

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

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