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

Capacitor 8은 기본적으로 Swift Package Manager(SPM)로 iOS 프로젝트를 생성합니다. CocoaPods를 아직 사용 중인 기존 앱도 이전할 수 있지만, 앱에 native iOS 커스터마이징이 얼마나 많은지에 따라 가장 안전한 경로는 달라집니다.

이 가이드에서는 변경 사항, 백업해야 하는 항목, 그리고 두 가지 실용적인 이전 경로를 안내합니다: Capacitor 이전 도우미를 사용하거나 iOS 프로젝트를 SPM로 재구성하는 방법

이제 이전하는 이유는 무엇인가요

CocoaPods는 읽기 전용 트렁크 방향으로 이동하고 있습니다. 현재 계획은 CocoaPods 트렁크가 2026년 12월 2일. 기존 빌드는 작동해야 하지만, 트렁크에 의존하는 새로운 릴리즈와 의존성 업데이트에는 이후 트렁크에서 배포되지 않을 것입니다.

SPM은 Capacitor도 향하는 방향입니다. Capacitor은 Capacitor 6부터 CocoaPods 또는 SPM를 지원해 왔으며, Capacitor 8은 iOS SPM 프로젝트를 기본 템플릿으로 생성합니다.

Capacitor SPM 프로젝트에서 변경되는 항목

Migrating from CocoaPods to SPM은 iOS 의존성 layer를 대체합니다. 웹 앱, 안드로이드 프로젝트 및 대부분의 Capacitor 워크플로우 명령은 동일합니다.

CapApp-SPM은 Podfile을 대체합니다.

CocoaPods 앱에서 iOS 의존성을 통해 ios/App/Podfile, Podfile.lock, Pods/, 그리고 생성된 .xcworkspace.

SPM 앱에서 Capacitor은 지역 패키지 이름으로 CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM debug.xcconfig은 Pods 구성 설정을 대체합니다.

이동 보조 도구는 또한 생성된

파일을 생성합니다. 이 파일은 CocoaPods가 생성한 xcconfig 파일을 통해 제공하던 빌드 설정을 포함합니다. debug.xcconfig이동 후, 보조 도구가 알려주면 Xcode 프로젝트 구성에

를 추가해야 할 수 있습니다. debug.xcconfig __CAPGO_KEEP_0__ creates a local package named __CAPGO_KEEP_1__

모든 플러그인은 SPM을 지원해야 합니다.

CocoaPods와 SPM을 같은 Capacitor iOS 프로젝트에서 혼용할 수 없습니다. 이전에 마이그레이션하기 전에 모든 Capacitor 및 Cordova 플러그인을 확인하세요. package.json.

SPM을 아직 지원하지 않는 플러그인이 있다면, 업데이트하거나 대체하거나 플러그인을 먼저 마이그레이션하세요. 간단한 Swift 플러그인은 종종 Ionic의 capacitor-plugin-converter하지만 Objective-C 및 Swift 레이아웃이 더 복잡한 플러그인은 수동 작업이 필요할 수 있습니다.

백업해야 할 것

clean git branch에서 시작하고 iOS 프로젝트를 조작하기 전에 현재 상태를 커밋하세요. 그런 다음 앱이 의존하는 네이티브 파일 목록을 만드세요.

보존해야 할 일반 파일 ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftFirebase를 사용하는 앱이 있다면
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist커스텀
파일 .xcconfig files
등록 설정, 번들 식별자, 팀 ID 및 배포 프로파일 설정

표준 Capacitor 템플릿 외부에서 추가한 원시 스위프트, 오브젝티브-C, 프레임워크, 확장 또는 SDK 파일을 보존하세요.

Option 1: Capacitor 마이그레이션 어시스턴트를 사용하세요.

iOS 프로젝트에 사용자 지정 원시 편집이 있는 경우 이 경로를 사용하세요.

Capacitor 프로젝트의 루트에서 어시스턴트를 실행하세요:

bunx cap spm-migration-assistant

어시스턴트는 CocoaPods 인프라를 제거하고, 로컬 패키지를 생성하고, 설치된 플러그인에서 패키지 참조를 생성하고, 생성된 SPM 구성 파일을 만듭니다. CapApp-SPM 완료되면 프로젝트를 열어 주세요:

그런 다음 어시스턴트가 출력한 수동 Xcode 단계를 따르세요. 대부분의 프로젝트의 경우:

bunx cap open ios

로컬 패키지 종속성을 추가하세요.

생성된 __CAPGO_KEEP_0__를 추가하세요. CapApp-SPM 생성된 __CAPGO_KEEP_0__를 추가하세요.
생성된 __CAPGO_KEEP_0__를 추가하세요. debug.xcconfig 앱 설정에 추가합니다.
SPM으로 변환되지 않은 플러그인에 대한 경고를 해결하십시오.
CI를 업데이트하기 전에 Xcode 앱을 한 번 빌드하십시오.

Xcode 프로젝트가 빌드된 후 다시 싱크하십시오:

bunx cap sync ios

iOS 프로젝트를 SPM으로 다시 구축하는 옵션 2:

디렉토리가 기본 __CAPGO_KEEP_0__ 템플릿과 가깝고 안전하게 커스텀 파일을 복원할 수 있는 경우 사용하세요. ios/ 새로운 앱의 경우, Capacitor 8는 iOS를 추가할 때 기본적으로 SPM을 사용합니다.

First, make sure the files listed in the backup section are committed or copied somewhere safe. Then remove and recreate the iOS project with SPM:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Restore the native files your app needs, then open the project:

bunx cap open ios

This path is often cleaner than an in-place migration because it gives you a fresh Capacitor 8 iOS template. The tradeoff is that you must carefully reapply signing, entitlements, Firebase files, native source changes, and any custom Xcode settings.

New Capacitor apps

Use this path when your directory is close to the default Capacitor template and you can safely restore custom files afterward.

bunx cap add ios

If you need to be explicit, you can still pass the package manager option:

bunx cap add ios --packagemanager SPM

CI를 업데이트하기 전에 마이그레이션

앱이 로컬에서 빌드되면 CI/CD를 업데이트하여 더 이상 CocoaPods를 가정하지 않도록 하세요.

다음 단계를 제거하세요:

pod install

또한 다음 캐시를 제거하세요:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods 스펙 저장소, 워크플로우가 이 앱만을 위해 캐시한 경우

정규 웹 빌드와 Capacitor 동기화 단계를 유지하세요. 일반적인 iOS 작업은 자바스크립트 의존성을 설치하고 웹 자산을 빌드한 다음 Capacitor를 동기화하고 Xcode로 빌드해야 합니다.

bun install --frozen-lockfile
bun run build
bunx cap sync ios

마이그레이션 체크리스트

마이그레이션 이전:

새로운 git branch를 생성하세요.
현재 작업 중인 앱을 커밋하세요.
모든 플러그인이 SPM을 지원하는지 확인하세요.
iOS 파일 및 서명 설정을 기록하세요.
앱이 마이그레이션되기 전에 빌드가 확인됩니다.

마이그레이션 중:

Run bunx cap spm-migration-assistant 또는 다시 scaffold ios/.
추가 CapApp-SPM Xcode에 필요할 경우 추가
추가 debug.xcconfig Xcode에 필요할 경우 추가
앱에 특화된 네이티브 파일을 복원하세요.
Run bunx cap sync ios.

마이그레이션 후:

Xcode에서 앱을 빌드하고 실행하세요.
CocoaPods 파일을 모두 삭제하세요.
삭제 pod install CI에서
릴리즈 서명이 여전히 작동하는지 확인하세요.
실제 기기와 시뮬레이터에서 적어도 한 번씩 앱을 실행한 후에 배포하세요.

문제 해결

Xcode가 패키지를 해결할 수 없으면, Xcode에서 패키지 캐시를 초기화하고 다시 실행하세요. bunx cap sync ios 이전 버전의 플러그인으로 인해 마이그레이션 실패하는 경우, 플러그인이 SPM 지원을 위한 최신 버전이 있는지 확인하세요. 관리하는 플러그인인 경우, 플러그인 패키지를 먼저 마이그레이션한 후 앱 마이그레이션으로 돌아가세요.

앱이 로컬에서 빌드되지만 CI에서 실패하는 경우, 오래된 CocoaPods 가정 중 하나를 확인하세요. 일반적인 원인은 강제된 빌드 경로 또는 오래된 캐시입니다.

Forced build path, stale .xcworkspace old CocoaPods assumptions pod install 명령, 또는 캐싱 Pods/ 이전 빌드에서 가져온다.

결론

Swift Package Manager로 Capacitor 앱을 마이그레이션하는 것은 주로 iOS 의존성 연결을 대체하는 것이다. CapApp-SPM takes over the dependency references, debug.xcconfig 생성된 CocoaPods 빌드 구성이 대체되고, CI는 더 이상 pod install.

사용자 지정 iOS 프로젝트의 경우 시작하려면 bunx cap spm-migration-assistant. 기본 템플릿과 가까운 프로젝트의 경우, 깨끗한 SPM 재구성은 종종 더 빠르고 이해하기 쉬운 방법이다.

자원

Capacitor 앱을 Swift Package Manager로 이전하는 방법에서 계속

__CAPGO_KEEP_0__을 사용하고 있다면 Capacitor 앱을 Swift Package Manager로 이전하는 방법 __CAPGO_KEEP_0__을 계획하고 기업 운영을 위해 연결하려면 __CAPGO_KEEP_0__ Enterprise Capgo Enterprise에서 Capgo 제품 워크플로 for the product workflow in Capgo Enterprise, __CAPGO_KEEP_0__ Alternatives에서 제품 워크플로 __CAPGO_KEEP_0__ Alternatives에서 제품 워크플로 Capgo Consulting Capgo Consulting Capgo Consulting 제품 워크플로우에 대한 Capgo 컨설팅 및 Capgo 프리미엄 지원 제품 워크플로우에 대한 Capgo 프리미엄 지원.