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

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

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 지점이 깨끗해야 합니다.

다음으로, __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, 만약 존재한다
custom .xcconfig 커스텀
파일
Swift 앱 확장, 네이티브 Swift 파일, Objective-C 파일, 또는 임베디드 프레임워크

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

마이그레이션 도우미 사용

대부분의 기존 앱의 경우 공식 Capacitor 마이그레이션 도우미로 시작하세요:

npx cap spm-migration-assistant

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

iOS 프로젝트를 열어보세요.

npx cap open ios

Xcode 단계 완료

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

확인

Confirm CapApp-SPM is
애플리케이션 목표 링크가 생성된 패키지 제품과 연결되어 있는지 확인하세요.
생성된 패키지를 프로젝트 구성에 추가하십시오. 조언자에게 추가를 요청하는 경우. debug.xcconfig Xcode에서 패키지 경고를 해결하십시오.
Xcode에서 앱을 한 번 빌드하십시오.
Xcode가 패키지를 해결할 수 없다면, "파일 > 패키지 > 패키지 캐시 초기화"를 사용하십시오. 그리고 패키지를 다시 해결하십시오.

Xcode가 구성되면 터미널로 돌아가 __CAPGO_KEEP_0__를同步하십시오: 파일 > 패키지 > 패키지 캐시 초기화앱이 푸시 알림, 연관된 도메인, 배경 모드, 앱 그룹, Firebase, 또는 네이티브 __CAPGO_KEEP_0__ 구성과 같은 기능을 사용한다면, 빌드가 성공한 후 시뮬레이터 또는 기기에서 해당 흐름을 실행하십시오.

재同步 및 다시 빌드

터미널로 돌아가 Capacitor를同步하세요.

npx cap sync ios

Then build from Xcode again. Do not treat the migration as done until a clean build works from Xcode, because release signing, entitlements, app extensions, and package resolution are validated there.

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.

대안: SPM으로 iOS 다시 생성

만약 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

CocoaPods 잔여물 정리

SPM 앱 빌드 후에, 로컬 스크립트와 CI에서 CocoaPods에 대한 가정들을 제거하라.

다음과 같은 단계를 제거하라:

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를 프로젝트 또는 워크스페이스 경로로 업데이트하여 이동 후 존재하는 경로로 업데이트하십시오. 오래된 CocoaPods 경로를 그냥 둘 이유는 없습니다.

문제 해결

의존성 충돌을 경고하는 도우미

어시스턴트가 불일치하는 의존성을 경고한다면

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

Xcode가 패키지를 해결할 수 없다면 CapApp-SPM Xcode에서 패키지 캐시를 초기화하고 npx cap sync ios again.

앱이 로컬에서 빌드되지만 CI가 실패한다면

이러한 CocoaPods 가정을 찾으세요: pod install, Pods/ 캐시 Podfile.lock 캐시 키, 또는 삭제 된 대상으로 지시하는 빌드 명령 .xcworkspace.

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

이전의 Xcode 대상과 이전 프로젝트를 비교하여 bundle 식별자, 팀, 프로비전 프로파일, 권한 파일, 기능, 확장 설정을 복원하세요.

이동 체크리스트

이전 이동 전:

브랜치를 생성하세요.
현재 iOS 앱이 빌드되는지 확인하세요.
작업 상태를 커밋하세요.
사용자 정의 네이티브 파일과 인증서 설정을 목록하세요.
이미 최신 SPM 호환 버전이 출시된 네이티브 의존성을 업데이트하세요.

이중 이주:

실행 npx cap spm-migration-assistant.
Xcode에서 프로젝트를 열고 npx cap open ios.
추가 CapApp-SPM Capacitor를 추가합니다.
추가 debug.xcconfig Capacitor를 추가합니다.
Xcode에서 필요할 경우.
실행 npx cap sync ios.

패키지 경고를 해결합니다.

이중 이주 후:
Xcode에서 앱을 빌드합니다.
CI에서 CocoaPods 명령어를 제거하십시오.
CocoaPods 전용 캐시를 제거하십시오.
아카이브 및 릴리즈 서명 확인하십시오.

이번 이주를 위해 Capgo 기술을 사용하십시오.

AI agent를 사용하여 이주를 처리하는 경우 __CAPGO_KEEP_0__ 기술에서 시작하십시오. Capgo 기술 앱 구조를 변경하기 전에 리뷰하십시오.

capacitor-best-practices SPM 이주 및 Xcode 후속 작업을 계획하십시오. ios/.
cocoapods-to-spm 빌드 PIPELINE에서 CocoaPods 가정치를 제거하십시오.
capacitor-ci-cd 그리고
debugging-capacitor and ios-android-logs __CAPGO_KEEP_0__

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 자원

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