Capacitor 8은 Swift Package Manager (SPM)으로 기본적으로 새로운 iOS 프로젝트를 생성합니다. CocoaPods를 아직 사용 중인 기존 앱도 마이그레이션할 수 있지만, 앱에 얼마나 많은 네이티브 iOS 커스터마이징이 있는지에 따라 가장 안전한 경로가 달라집니다.
이 안내서에서는 변경 사항, 백업해야 하는 것, 그리고 두 가지 실제 마이그레이션 경로인 Capacitor 마이그레이션 어시스턴트를 사용하는 방법 또는 iOS 프로젝트를 다시 구축하여 SPM을 사용하는 방법을 안내합니다.
왜 지금 마이그레이션해야 하나요
CocoaPods는 읽기 전용 트렁크 방향으로 이동하고 있습니다. 현재 계획은 CocoaPods 트렁크가 December 2, 2026에 새로운 podspecs를 더 이상 수용하지 않도록 하는 것입니다. 기존 빌드는 계속 작동해야 하지만, 트렁크를 사용하는 새로운 릴리즈와 의존성 업데이트는 트렁크 이후에 더 이상那里에 게시되지 않습니다. SPM은 __CAPGO_KEEP_0__도 향하는 방향입니다. __CAPGO_KEEP_1__은 __CAPGO_KEEP_2__ 6부터 CocoaPods 또는 SPM을 선택할 수 있는 지원을 제공했으며, __CAPGO_KEEP_3__ 8은 iOS SPM 프로젝트를 기본 템플릿으로 생성합니다.__CAPGO_KEEP_0__ SPM 프로젝트에서 변경되는 것
SPM is also the direction Capacitor is moving. Capacitor has supported choosing CocoaPods or SPM since Capacitor 6, and Capacitor 8 now creates iOS SPM projects as the default template.
What changes in a Capacitor SPM project
Migrating from CocoaPods to SPM replaces the iOS dependency layer. The web app, Android project, and most Capacitor workflow commands stay the same.
그리고 생성된
__CAPGO_KEEP_0__ ios/App/Podfile, Podfile.lock, Pods/__CAPGO_KEEP_1__ .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 debug.xcconfig은 Pods 구성이 대체됩니다.
migration assistant가 생성한 __CAPGO_KEEP_0__은 CocoaPods가 생성한 xcconfig 파일과 유사한 빌드 설정을 포함합니다.
migration 후, Xcode 프로젝트 구성에 __CAPGO_KEEP_0__을 추가해야 할 수 있습니다. migration assistant가 추가를 요구한다면. debug.xcconfigSPM을 지원하는 플러그인이 모두 있어야 합니다.
CocoaPods와 SPM을 혼합하여 iOS 프로젝트를 생성할 수 없습니다. migration 전에 모든 플러그인과 Cordova 플러그인을 확인하십시오. debug.xcconfig SPM을 지원하지 않는 플러그인이 있다면, 플러그인을 업데이트하거나 대체하거나, 플러그인 이전을 먼저 진행하십시오. 간단한 Swift 플러그인은 Ionic의 __CAPGO_KEEP_1__을 사용하여 쉽게 변환할 수 있지만, Objective-C와 Swift의 복잡한 레이아웃을 가진 플러그인은 수동 작업이 필요합니다.
__CAPGO_KEEP_0__
You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.
__CAPGO_KEEP_2__ capacitor-plugin-converter__CAPGO_KEEP_0__
백업해야 하는 첫 번째 항목은 무엇인가요?
iOS 프로젝트를 건드리지 않고 현재 상태를 커밋한 후 clean git branch에서 시작하세요. 그런 다음 앱이 의존하는 네이티브 파일 목록을 만드세요.
보존해야 하는 일반 파일 ios/App/ include:
App/Info.plistApp/AppDelegate.swiftApp/SceneDelegate.swiftFirebase를 사용하는 경우App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plistFirebase를 사용하는 경우- 커스텀
.xcconfig커스텀 파일 - 인증 설정, 번들 식별자, 팀 ID, 프로비전 프로파일 설정
표준 Capacitor 템플릿 외부에서 추가한 네이티브 스위프트, 오브젝티브-C, 프레임워크, 확장, 또는 SDK 파일도 보존하세요.
Option 1: Capacitor 마이그레이션 어시스턴트 사용
iOS 프로젝트에 커스텀 네이티브 편집이 있는 경우 사용하세요.
프로젝트의 루트에서 Capacitor_assistant를 실행하세요:
bunx cap spm-migration-assistantassistant는 CocoaPods 인프라를 제거하고, 로컬 패키지를 생성하고, 설치된 플러그인으로부터 패키지 참조를 생성하고, 생성된 SPM 구성 파일을 만듭니다. CapApp-SPM 완료되면 프로젝트를 열어주세요:
그 다음에 assistant가 출력한 수동 Xcode 단계를 따르세요. 대부분의 프로젝트에서는 다음과 같은 단계를 따르세요:
bunx cap open ios로컬 패키지 종속성을 추가하세요.
- 생성된 를 앱 구성에 추가하세요.
CapApp-SPMSPM으로 변환되지 않은 플러그인에 대한 경고를 해결하세요. - CI를 업데이트하기 전에 앱을 Xcode에서 한 번 빌드하세요.
debug.xcconfigXcode 프로젝트가 빌드된 후 다시 싱크하세요: - Add
- as a local package dependency.
Add the generated
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.
필요한 네이티브 파일을 복원한 후 프로젝트를 열어보세요:
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 iosCI 업데이트하기
bunx cap add ios --packagemanager SPM앱이 로컬에서 빌드되면, CocoaPods를 가정하지 않는 CI/CD를 업데이트하세요.
CI/CD에서 실행하는 단계를 제거하세요:
__CAPGO_KEEP_0__ 8 iOS 템플릿
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 파일 및 서명 설정을 기록하세요.
- 이동 전 앱이 빌드되는지 확인하세요.
이동 중:
- 실행
bunx cap spm-migration-assistant또는 다시 구조화ios/. - 추가
CapApp-SPMXcode에 필요 시 추가 - 추가
debug.xcconfigXcode에 필요 시 추가 - 앱에 특화된 네이티브 파일 복원
- 실행
bunx cap sync ios.
이주 후:
- Xcode에서 앱 빌드 및 실행
- 남아 있는 CocoaPods 파일 삭제
- CI에서 삭제
pod installCI에서 삭제 - 릴리스 서명이 여전히 작동하는지 확인하세요.
- 적어도 하나의 시뮬레이터와 하나의 실제 기기에서 앱을 실행하세요.
문제 해결
페이지/영역: 지원 / 프리미엄 지원 페이지 또는 푸터 지원 섹션. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (지원 정책 문제 해결 제목). bunx cap sync ios Xcode가 패키지를 해결할 수 없으면 Xcode에서 패키지 캐시를 초기화하고 다시 실행하세요.
다시 실행하세요.
플러그인으로 인해 마이그레이션 실패하는 경우 플러그인이 SPM 지원을 위한 최신 릴리스를 가지고 있는지 확인하세요. 유지 관리하는 플러그인이 있는 경우 플러그인 패키지를 먼저 마이그레이션하고 앱 마이그레이션으로 돌아가세요. .xcworkspace 앱이 로컬에서 빌드되지만 CI가 실패하는 경우 CocoaPods의 오래된 가정에 대해 확인하세요. 일반적인 원인은 강제된 빌드 경로, 오래된 명령, 또는 이전 빌드에서 캐싱하는 것입니다. pod install 결론 Pods/ __CAPGO_KEEP_0__ 앱을 Swift Package Manager로 마이그레이팅하는 것은 주로 iOS 의존성 연결을 대체하는 것입니다.
__CAPGO_KEEP_0__
Capacitor CapApp-SPM 의존성 참조를 대체합니다. debug.xcconfig 생성된 CocoaPods 빌드 구성이 대체되고 CI는 더 이상 필요하지 않습니다. pod install.
커스텀 iOS 프로젝트의 경우 시작하세요. bunx cap spm-migration-assistant. 기본 템플릿과 가까운 프로젝트의 경우, 깨끗한 SPM 재구성은 종종 더 빠르고 이해하기 쉬운 방법입니다.
자원
- Capacitor Swift Package Manager documentation
- Capacitor 8 update guide
- CocoaPods 트렁크 읽기 전용 계획
- capacitor-plugin-converter
How to Migrate a Capacitor App to Swift Package Manager
__CAPGO_KEEP_0__ 앱을 Swift Package Manager로 마이그레이션하는 방법에 대해 계속 진행하세요. Capacitor 앱을 Swift Package Manager로 마이그레이션하는 방법에 대해 설명합니다. 이동 및 기업 운영을 계획하고 연결하세요. Capgo 기업 Capgo Enterprise 아이오닉 기업 플러그인 대체품 __CAPGO_KEEP_0__ Alternatives Capgo Alternatives Capgo 컨설팅 Capgo Consulting Capgo 프리미엄 지원 Capgo Premium Support for the product workflow in Capgo Premium Support.
