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

Capacitor 8은 Swift Package Manager (SPM)로 iOS 프로젝트를 생성합니다. 기존 앱이 CocoaPods를 사용하고 있다면도 마이그레이션할 수 있지만, 앱에 native iOS 커스터마이즈가 얼마나 많은지에 따라 가장 안전한 경로는 달라집니다.

이 안내서에서는 변경 사항, 백업해야 하는 것, 그리고 두 가지 실제 마이그레이션 경로인 Capacitor 마이그레이션 어시스턴트를 사용하는 방법 또는 iOS 프로젝트를 SPM로 다시 구축하는 방법을 안내합니다.

왜 지금 마이그레이션해야 하나요

CocoaPods는 읽기 전용 트렁크 방향으로 이동하고 있습니다. 현재 계획은 CocoaPods 트렁크가 새로운 podspecs를 받지 않도록 2026년 12월 2일기존 빌드는 계속 작동해야 하지만, 트렁크를 의존하는 새로운 릴리즈와 의존성 업데이트는 트렁크에 게시되지 않습니다.

SPM은 Capacitor도 같은 방향으로 이동하고 있습니다. Capacitor은 Capacitor 6부터 CocoaPods 또는 SPM를 선택할 수 있었고, Capacitor 8은 iOS SPM 프로젝트를 기본 템플릿으로 생성합니다.

Capacitor SPM 프로젝트에서 변경 사항은 무엇입니까

CocoaPods에서 SPM으로 마이그레이션하면 iOS 의존성层을 대체합니다. 웹 앱, Android 프로젝트, 그리고 대부분의 Capacitor 워크플로우 명령은 동일하게 유지됩니다.

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

CocoaPods 앱에서 iOS 의존성을 연결하는 것은 ios/App/Podfile, Podfile.lock, Pods/그리고 생성된 .xcworkspace.

In SPM 앱에서, Capacitor은 로컬 패키지 이름을 생성합니다. CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM __CAPGO_KEEP_1__ __CAPGO_KEEP_2__은 플러그인 동기화 시 업데이트되므로, 수동으로 편집하지 말고 자동으로 생성된 출력으로 다루세요.

debug.xcconfig은 Pods 구성이 대체됩니다.

이동 보조 도구는 또한 생성된 debug.xcconfig파일을 생성합니다. 이 파일에는 CocoaPods가 xcconfig 파일을 생성하여 제공하던 빌드 설정이 포함되어 있습니다.

이동 후, 보조 도구가 알려주면 Xcode 프로젝트 구성에 debug.xcconfig 을 추가해야 할 수 있습니다.

SPM을 지원하는 플러그인은 모두 있어야 합니다.

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

SPM을 아직 지원하지 않는 플러그인이 있다면, 플러그인을 업데이트하거나 대체하거나, 플러그인을 먼저 이동하세요. 단순한 Swift 플러그인은 종종 Ionic의 capacitor-plugin-converter을 사용하여 변환할 수 있지만, 더 복잡한 Objective-C와 Swift 레이아웃을 가진 플러그인은 수동으로 작업해야 할 수 있습니다.

What to back up first

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

기본적으로 보존해야 하는 파일 ios/App/ include: __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, Firebase를 사용한다면
사용자 정의 .xcconfig 파일
인증 설정, 번들 식별자, 팀 ID, 및 프로비전 프로파일 설정

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

Option 1: Capacitor 마이그레이션 어시스턴트 사용

iOS 프로젝트가 사용자 정의 네이티브 편집을 포함하고 있고 그 편집을 잃고 싶지 않다면 이 경로를 사용하세요.

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

bunx cap spm-migration-assistant

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

그 다음 어시스턴트가 출력한 수동 Xcode 단계를 따르십시오. 대부분의 프로젝트에서는 다음과 같습니다:

bunx cap open ios

로컬 패키지 의존성을 추가하십시오.

생성된 를 앱 구성에 추가하십시오. CapApp-SPM 플러그인이 SPM으로 변환되지 못한 것에 대한 경고를 해결하십시오.
CI를 업데이트하기 전에 앱을 Xcode에서 한 번 빌드하십시오. debug.xcconfig Xcode 프로젝트가 빌드된 후 다시 싱크하십시오:
__CAPGO_KEEP_0__
어시스턴트

Xcode

bunx cap sync ios

Option 2: iOS 프로젝트를 SPM으로 재구성하세요.

이 경로를 사용할 때, 디렉토리가 기본 __CAPGO_KEEP_0__ 템플릿과 가깝고, 이후에 커스텀 파일을 복원할 수 있는 경우에 사용하세요. ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

네이티브 파일이 필요하다면 복원하고, 프로젝트를 열어보세요.

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

이 경로는 프로젝트를 재구성하는 경우에 더 깨끗한 __CAPGO_KEEP_0__ 8 iOS 템플릿을 제공합니다. 그러나, 서명, 권한, Firebase 파일, 네이티브 소스 변경, 커스텀 Xcode 설정 등에 대한 조심스러운 재적용이 필요합니다.

bunx cap open ios

새로운 Capacitor 앱

새로운 앱의 경우, Capacitor 8는 iOS를 추가할 때 SPM을 기본으로 사용합니다.

For a new app, Capacitor 8 uses SPM by default when adding iOS:

bunx cap add ios

CI 업데이트하기

bunx cap add ios --packagemanager SPM

앱이 로컬에서 빌드되면, CocoaPods를 가정하지 않는 CI/CD를 업데이트하세요.

다음 단계를 제거하세요:

run

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 파일 및 서명 설정을 기록하세요.
이동 전 앱이 빌드되는지 확인하세요.

이동 중:

실행 bunx cap spm-migration-assistant or re-scaffold ios/.
Add CapApp-SPM Xcode에 필요할 경우 추가.
Add debug.xcconfig Xcode에 필요할 경우 추가.
앱에 특화된 네이티브 파일을 복원.
Run bunx cap sync ios.

이전 마이그레이션 후:

Xcode에서 앱을 빌드 및 실행.
CocoaPods 파일을 제거.
Remove pod install CI에서 제거.
릴리스 서명이 여전히 작동하는지 확인하세요.
배송하기 전에 앱을 최소한 한 개의 시뮬레이터와 한 개의 실제 기기에서 실행하세요.

문제 해결

__CAPGO_KEEP_0__ 앱을 Swift Package Manager로 마이그레이션하는 것은 iOS 의존성 연결을 대체하는 것에 대부분 있습니다. bunx cap sync ios Xcode가 패키지를 해결할 수 없으면 Xcode에서 패키지 캐시를 초기화하고 다시 실행하세요.

마이그레이션 실패가 플러그인 때문인 경우 플러그인이 SPM 지원을 위한 최신 릴리스를 가지고 있는지 확인하세요. 유지 관리하는 플러그인인 경우 플러그인 패키지를 먼저 마이그레이션하고 앱 마이그레이션으로 돌아가세요.

앱이 로컬에서 빌드되지만 CI가 실패하는 경우 오래된 CocoaPods 가정에 대해 확인하세요. 일반적인 원인은 강제된 빌드 경로, 오래된 명령, 이전 빌드에서 캐싱된 것입니다. .xcworkspace 결론 pod install Xcode가 패키지를 해결할 수 없으면 Xcode에서 패키지 캐시를 초기화하고 다시 실행하세요. 만약 마이그레이션 실패가 플러그인 때문인 경우 플러그인이 SPM 지원을 위한 최신 릴리스를 가지고 있는지 확인하세요. 유지 관리하는 플러그인인 경우 플러그인 패키지를 먼저 마이그레이션하고 앱 마이그레이션으로 돌아가세요. Pods/ 앱이 로컬에서 빌드되지만 CI가 실패하는 경우 오래된 CocoaPods 가정에 대해 확인하세요. 일반적인 원인은 강제된 빌드 경로, 오래된 명령, 이전 빌드에서 캐싱된 것입니다.

앱을 최소한 한 개의 시뮬레이터와 한 개의 실제 기기에서 실행하세요.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM __CAPGO_KEEP_0__ 의 종속성 참조를 대체하고 CocoaPods 빌드 구성이 생성되며 CI가 더 이상 필요하지 않습니다. debug.xcconfig __CAPGO_KEEP_0__ CI가 더 이상 필요하지 않습니다. pod install.

iOS 프로젝트를 커스터마이즈하려면 bunx cap spm-migration-assistant__CAPGO_KEEP_0__ 프로젝트는 기본 템플릿과 가깝다면, SPM 재구성은 더 빠르고 이해하기 쉬운 경우가 많습니다.

자원

Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법에 대해 계속 진행하세요.

__CAPGO_KEEP_0__ 앱을 Swift Package Manager로 마이그레이션하는 방법에 대해 계속 진행하세요. Capacitor를 사용하고 있다면 migration과 기업 운영을 계획하고 연결하세요. Capgo Enterprise Capgo Enterprise에서 제품 워크플로우를 위해 Ionic Enterprise Plugin Alternatives Ionic Enterprise Plugin Alternatives에서 제품 워크플로우를 위해 Capgo Alternatives Capgo Alternatives에서 제품 워크플로우를 위해 Capgo Consulting Capgo Consulting을 통해 제품 워크플로우를 위해 Capgo Premium Support Capgo Premium Support를 통해 제품 워크플로우를 위해