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

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

This guide walks through what changes, what to back up, and the two practical migration paths: using the Capacitor migration assistant or re-scaffolding the iOS project with SPM.

CocoaPods는 읽기 전용 트렁크로 이동하고 있습니다. 현재 계획은 CocoaPods 트렁크가

2026년 12월 2일 __CAPGO_KEEP_0__. 기존 빌드는 계속 작동해야 하지만, 트렁크에 의존하는 새로운 릴리즈 및 의존성 업데이트 는 Switch 이후에 그곳에 게시되지 않을 것입니다.

SPM은 Capacitor도 향하는 방향입니다. Capacitor은 CocoaPods 또는 SPM을 선택하는 기능을 Capacitor 6부터 지원하고, Capacitor 8에서는 iOS SPM 프로젝트를 기본 템플릿으로 생성합니다.

Capacitor SPM 프로젝트에서 변경되는 것은 무엇인가요

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

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

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

SPM 앱에서, Capacitor은 로컬 패키지 이름으로 CapApp-SPM를 생성합니다. 이 패키지는 Capacitor에서 native iOS 플러그인 의존성을 참조하는 중앙 장소가 됩니다. Capacitor CLI 업데이트는 CapApp-SPM 플러그인 동기화를 할 때마다 업데이트되므로, 수동으로 편집하지 말고 generated output로 처리하십시오.

debug.xcconfig은 Pods 구성 파일을 대체합니다.

마이그레이션 어시스턴트도 generated debug.xcconfig. 이 파일은 CocoaPods가 생성한 xcconfig 파일을 통해 제공하던 빌드 설정을 담고 있습니다.

이동 후, 보조 도구가 알려주신 대로 Xcode 프로젝트 구성에 debug.xcconfig 모든 플러그인은 SPM을 지원해야 합니다.

CocoaPods와 SPM을 같은 iOS 프로젝트에 혼용할 수 없습니다. 이전에 이주하기 전에 모든

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

하지만 더 복잡한 Objective-C와 Swift 레이아웃을 가진 플러그인은 수동 작업이 필요할 수 있습니다. capacitor-plugin-converter먼저 백업해야 할 것

clean git branch에서 시작하여 현재 상태를 커밋한 후 iOS 프로젝트에 손을 대기 전에 native 파일을 앱이 의존하는 파일을 나열하세요.

보존해야 할 일반 파일

include: ios/App/ , 앱이 하나라도 있다면

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftinclude:
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistFirebase를 사용하면
사용자 정의 .xcconfig 파일
인증 설정, 번들 식별자, 팀 ID 및 배포 설정

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

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

iOS 프로젝트가 사용자 정의 원시 편집이 포함되어 있는 경우 이 경로를 사용하세요.

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

bunx cap spm-migration-assistant

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

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

bunx cap open ios

Then follow the manual Xcode steps printed by the assistant. In most projects this means:

추가 CapApp-SPM __CAPGO_KEEP_0__을 지역 패키지 의존성으로 추가합니다.
__CAPGO_KEEP_0__를 앱 구성에 추가합니다. debug.xcconfig SPM으로 변환되지 않은 플러그인에 대한 경고를 해결합니다.
CI를 업데이트하기 전에 Xcode에서 앱을 한 번 빌드하세요.
Xcode 프로젝트가 빌드된 후 다시 싱크하세요:

Option 2: SPM으로 iOS 프로젝트를 다시 구축하세요

bunx cap sync ios

이 경로를 사용할 때 __CAPGO_KEEP_0__ 디렉토리가 기본 템플릿과 가깝고 안전하게 커스텀 파일을 복원할 수 있습니다.

먼저 백업 섹션에 나열된 파일이 커밋되거나 안전한 곳에 복사되어 있는지 확인하세요. 그런 다음 SPM으로 iOS 프로젝트를 삭제하고 다시 생성하세요: 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

앱이 필요로 하는 네이티브 파일을 복원한 후 프로젝트를 열어주세요.

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.

새 Capacitor 앱

새 앱을 만들 때, Capacitor 8는 iOS에 대해 SPM을 기본으로 사용합니다.

bunx cap add ios

explicit하게 지정할 필요가 있다면, 여전히 패키지 매니저 옵션을 전달할 수 있습니다.

bunx cap add ios --packagemanager SPM

CI 업그레이드

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

실행되는 단계를 제거하십시오.

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 or re-scaffold ios/.
Add CapApp-SPM Xcode에서 필요할 경우 추가하세요.
Add debug.xcconfig Xcode에서 필요할 경우 추가하세요.
앱에 특화된 네이티브 파일을 복원합니다.
실행 bunx cap sync ios.

이주 후:

Xcode에서 앱을 빌드하고 실행합니다.
CocoaPods의 남은 파일을 삭제합니다.
삭제 pod install CI에서 제거합니다.
발행을 위해 여전히 서명이 작동하는지 확인합니다.
최소한 한 개의 시뮬레이터와 한 개의 실제 장치에서 앱을 실행하기 전에 배송합니다.

문제 해결

Xcode가 패키지를 해결할 수 없으면 Xcode에서 패키지 캐시를 초기화하고 다시 실행하세요. bunx cap sync ios If Xcode cannot resolve packages, reset package caches from Xcode and run again.

이러한 마이그레이션은 플러그인이 실패하는 경우, 플러그인이 SPM 지원을 위한 최신 릴리즈를 가지고 있는지 확인합니다. 유지 관리하는 플러그인인 경우, 플러그인 패키지를 먼저 마이그레이션하고 앱 마이그레이션으로 돌아갑니다.

앱이 로컬에서 빌드되지만 CI가 실패하는 경우, 오래된 CocoaPods 가정에 대해 확인합니다. 일반적인 원인은 강제된 빌드 경로,陈舊한 명령, 또는 이전 빌드에서 캐싱하는 것입니다. .xcworkspace 결론 pod install Swift Package Manager로 __CAPGO_KEEP_0__ 앱을 마이그레이션하는 것은 주로 iOS 의존성 연결을 대체하는 것입니다. Pods/ SPM이 의존성 참조를 대체하고, CocoaPods로 생성된 빌드 구성이 대체되고, CI가 더 이상 필요하지 않습니다.

사용자 지정 iOS 프로젝트의 경우,

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM 자원 debug.xcconfig When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced pod install.

build path, a stale bunx cap spm-migration-assistantcommand, or caching

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