Capacitor 8은 Swift Package Manager(SPM)로 기본적으로 새로운 iOS 프로젝트를 생성합니다. CocoaPods를 아직 사용 중인 기존 앱도 마이그레이션할 수 있지만, 앱에 얼마나 많은 네이티브 iOS 커스터마이징이 있는지에 따라 가장 안전한 경로는 달라집니다.
이 안내서에서는 변경되는 내용, 백업해야 하는 내용, 두 가지 실제 마이그레이션 경로인 Capacitor 마이그레이션 어시스턴트를 사용하는 방법과 iOS 프로젝트를 SPM로 재구성하는 방법을 안내합니다.
왜 지금 마이그레이션해야 하나요?
CocoaPods는 현재 CocoaPods 트렁크가 새로운 podspec을 더 이상 수용하지 않도록 계획 중입니다. 2026년 12월 2일. 기존 빌드는 계속 작동해야 하지만 Switch 이후에 Trunk에 의존하는 새로운 릴리즈 및 의존성 업데이트가 더 이상那里에 게시되지 않습니다.
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 를 동기화할 때마다 업데이트되므로, 수동으로 편집하지 마십시오.
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.
과 Cordova 플러그인을 확인하세요. capacitor-plugin-converterSPM을 아직 지원하지 않는 플러그인이 있다면, 플러그인을 업데이트하거나 대체하거나 플러그인을 먼저 이주하세요. 단순한 Swift 플러그인은 종종 Ionic의
을 통해 변환할 수 있지만 더 복잡한 Objective-C와 Swift 레이아웃을 가진 플러그인은 수동 작업이 필요합니다.
백업해야 할 것들
clean git branch에서 시작하고 iOS 프로젝트를 건드리지 전에 현재 상태를 커밋하세요. 그런 다음 앱이 의존하는 네이티브 파일 목록을 만드세요. ios/App/ 이동 전부터 보존해야 할 파일들
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swiftiOS SPM과 Cocoapods 대비 Capgo로의 이주 가이드App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plist앱이 하나만 있다면- Firebase를 사용한다면
.xcconfig커스텀 - 파일
Also preserve any native Swift, Objective-C, framework, extension, or SDK files you added outside the standard Capacitor template.
또한 표준 __CAPGO_KEEP_1__ 템플릿 외부에서 추가한 원본 Swift, Objective-C, 프레임워크, 확장, 또는 Capacitor 파일을 보존하세요.
Option 1: __CAPGO_KEEP_0__ 이주 도우미를 사용하세요
Run the assistant from the root of your Capacitor project:
bunx cap spm-migration-assistant프로젝트의 루트에서 도우미를 실행하세요: CapApp-SPM 도우미는 CocoaPods 인프라를 제거하고, 로컬 패키지를 생성하고, 설치된 플러그인에서 패키지 참조를 생성하고, 생성된 SPM 구성 파일을 만듭니다.
완료되면 프로젝트를 열어보세요:
bunx cap open ios그런 다음 어시스턴트가 출력하는 수동 Xcode 단계를 따르세요. 대부분의 프로젝트에서 이것은 다음과 같습니다:
- Add
CapApp-SPM로컬 패키지 종속성으로 추가합니다. - 생성된
debug.xcconfig앱 구성에 추가합니다. - SPM으로 변환되지 않은 플러그인에 대한 경고를 해결하세요.
- CI를 업데이트하기 전에 앱을 Xcode에서 한 번 빌드하세요.
Xcode 프로젝트가 빌드된 후 다시 동기화하세요:
bunx cap sync iosOption 2: iOS 프로젝트를 SPM으로 다시 구축
이 경로를 사용하세요. 디렉토리가 기본 __CAPGO_KEEP_0__ 템플릿과 가깝고 이후에 커스텀 파일을 복원할 수 있는 경우에요. ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.
Option 2: iOS 프로젝트를 SPM으로 다시 구축
rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios앱이 필요로 하는 원본 파일을 복원하고 프로젝트를 열어보세요:
bunx cap open ios이 경로는 원래 위치에서 마이그레이션하는 것보다 더 깨끗한 경로를 제공합니다. Capacitor 8 iOS 템플릿을 새로 받을 수 있습니다. 그러나 이 경우에는 신중하게 서명, 권한, Firebase 파일, 네이티브 소스 변경, 그리고 Xcode 설정을 다시 적용해야 합니다.
새 Capacitor 앱
새 앱을 만들 때, Capacitor 8는 iOS에 추가할 때 기본적으로 SPM을 사용합니다.
bunx cap add ios만약 명시적으로 패키지 매니저 옵션을 전달해야 한다면:
bunx cap add ios --packagemanager SPMCI 업데이트하기
앱이 로컬에서 빌드가 되면, CocoaPods를 사용하지 않는 CI/CD를 업데이트하세요.
실행하지 않는 단계를 제거하세요:
pod install또한 다음 캐시를 제거하세요:
ios/App/Podsios/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또는 재구성ios/. - Xcode에서 필요할 경우 Add
CapApp-SPMXcode에서 필요할 경우 Add - Run
debug.xcconfigXcode에서 필요할 경우. - 앱에 특화된 네이티브 파일을 복원합니다.
- 실행
bunx cap sync ios.
이동 후:
- Xcode에서 앱을 빌드하고 실행합니다.
- 남아 있는 CocoaPods 파일을 삭제합니다.
- 삭제
pod installCI에서 제거합니다. - 릴리즈 서명이 여전히 작동하는지 확인합니다.
- 배송 전에 최소한 한 개의 시뮬레이터와 한 개의 실제 기기에서 앱을 실행합니다.
문제 해결
페이지/영역: 지원 / 프리미엄 지원 페이지 또는 푸터 지원 섹션. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (지원 정책 문제 해결 제목). bunx cap sync ios 다시.
플러그인으로 인해 마이그레이션 실패하는 경우, 플러그인이 SPM 지원을 위한 최신 릴리즈를 가지고 있는지 확인하세요. 유지 관리하는 플러그인에 대해, 플러그인 패키지를 먼저 마이그레이션하고 앱 마이그레이션으로 돌아가세요.
앱이 로컬에서 빌드되지만 CI가 실패하는 경우, 오래된 CocoaPods 가정에 대해 확인하세요. 일반적인 원인은 강제된 빌드 경로,陈舊한 명령, 또는 이전 빌드에서 캐싱되는 것입니다. .xcworkspace 결론 pod install __CAPGO_KEEP_0__ 앱을 Swift Package Manager로 마이그레이팅하는 것은 주로 iOS 의존성 연결을 대체하는 것입니다. Pods/ SPM이 의존성 참조를 대체하고, CocoaPods로 생성된 빌드 구성이 대체되고, CI가 더 이상 필요하지 않습니다.
사용자 지정 iOS 프로젝트의 경우, 다음 단계를 시작하세요.
Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM takes over the dependency references, debug.xcconfig replaces generated CocoaPods build configuration, and CI no longer needs pod install.
For customized iOS projects, start with bunx cap spm-migration-assistant. For projects close to the default template, a clean SPM re-scaffold is often faster and easier to reason about.
자원
Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법에서 계속하세요
이미 __CAPGO_KEEP_0__을 사용하고 있다면 Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법 이전 단계에서 계획 및 기업 운영을 위해 연결하세요 Capgo Enterprise Capgo Enterprise를 사용하여 제품 워크플로우 아이오닉 엔터프라이즈 플러그인 대체품 Capgo 제품 워크플로우에 대한 Capgo 대안 for the product workflow in Capgo Alternatives, Capgo 컨설팅 Capgo 제품 워크플로우에 대한 Capgo 컨설팅 및 Capgo 프리미엄 지원 Capgo 제품 워크플로우에 대한 Capgo 프리미엄 지원.
