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

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.

__CAPGO_KEEP_0__ 앱의 변경 사항

Capacitor 앱은 CocoaPods에 의존하는 파일을 사용합니다:

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/보존해야 하는 일반 파일 및 설정은 다음과 같습니다:

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 마이그레이션 도우미를 시작하세요:

npx cap spm-migration-assistant

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

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

npx cap open ios

Xcode 단계를 완료하세요

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

확인

__CAPGO_KEEP_0__ CapApp-SPM Capacitor 앱을 SPM으로 마이그레이션하는 방법
생성된 패키지 제품이 앱 대상과 연결되어 있는지 확인하세요.
생성된 debug.xcconfig 프로젝트 설정에 생성된
Xcode에서 패키지 경고를 해결하세요.
Xcode에서 앱을 한 번 빌드하세요.

Xcode가 패키지를 해결할 수 없다면, File > Packages > Reset Package Caches를 선택한 후 패키지를 다시 해결하세요.

Xcode가 설정되면 터미널로 돌아가 __CAPGO_KEEP_0__를同步하세요:

After Xcode is configured, return to the terminal and sync Capacitor:

npx cap sync ios

마지막으로 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

만약 명시적으로 원하는 대로 유지할 수 있는 네이티브 파일과 서명 설정을 모두 커밋하거나 백업한 후 SPM으로 다시 생성하는 것이 더 빠를 수 있습니다.

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 가 로컬 패키스로 존재하는지 확인하고 다시 실행하십시오.

애플리케이션은 로컬에서 빌드되지만 CI가 실패합니다.

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

빌드 명령어에서 삭제된 것을 가리키는

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

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

이동 체크리스트

이전 이동 전:
브랜치를 생성하세요.
현재 iOS 앱이 빌드되는지 확인하세요.
작업 중인 상태를 커밋하세요.
새로운 SPM 호환 버전이 있는 native 의존성을 업데이트하십시오.

이동 중:

실행 npx cap spm-migration-assistant.
Xcode에서 프로젝트를 열어보십시오. npx cap open ios.
Xcode에서 필요 시 추가하십시오. CapApp-SPM Xcode에서 필요 시 추가하십시오.
패키지 경고를 해결하십시오. debug.xcconfig 실행
이동 후:
Xcode에서 앱을 빌드하십시오. npx cap sync ios.

Xcode에서 프로젝트를 열어보십시오.

Xcode에서 필요 시 추가하십시오.
Simulator 또는 기기에서 네이티브 기능 테스트
CIC에서 CocoaPods 명령어 제거
CocoaPods 전용 캐시 제거
아카이브 및 릴리즈 서명 확인

이동을 위해 Capgo 기술을 사용하십시오

AI agent가 이 과정을 처리하는 경우 __CAPGO_KEEP_0__ 기술에서 시작하십시오 Capgo Skills 앱 구조를 변경하기 전에 리뷰

capacitor-best-practices SPM 이동과 Xcode 후속 단계를 계획 ios/.
cocoapods-to-spm 빌드 PIPELINE에서 CocoaPods 가정 제거
capacitor-ci-cd 그리고
debugging-capacitor 컨텍스트: Capgo 마케팅 웹사이트. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 위치: trust.astro 페이지. ios-android-logs 이동 후 장치 전용 문제를 조사하기 위해.

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

결론

Capacitor 앱을 Swift Package Manager로 마이그레이션하는 것은 주로 iOS 종속성 관리 변경입니다. 가장 안전한 경로는 clean branch에서 시작하여 npx cap spm-migration-assistant__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__ npx cap add ios --packagemanager SPM iOS 프로젝트가 heavly 커스텀화되어 있다면, place에서 마이그레이션을 진행하고, default __CAPGO_KEEP_0__ template와 가깝다면,

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