Swift Package Manager로 Capacitor 앱을 마이그레이션하는 방법

이 안내서에서는 변경되는 내용, 백업해야 하는 내용, 그리고 두 가지 실제적인 이전 경로를 안내합니다: 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 트렁크가 새로운 podspec을 더 이상 수용하지 않도록 하는 것입니다.

CocoaPods trunk 2026년 12월 2일기존 빌드는 계속 작동해야 하지만 트렁크에 의존하는 새로운 릴리즈 및 의존성 업데이트 는 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.

In an SPM app, Capacitor creates a local package named CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM 를 생성합니다. 이 패키지는 __CAPGO_KEEP_0__이 네이티브 iOS 플러그인 의존성을 참조하는 중앙 장소가 됩니다. __CAPGO_KEEP_1__ __CAPGO_KEEP_2__은 플러그인 동기화를 통해 업데이트

되므로 수동으로 편집하지 말고 생성된 출력으로 다루세요.(debug.xcconfig는 Pods 구성이 대체됩니다.)

The migration assistant also creates a generated debug.xcconfig이 파일은 CocoaPods가 xcconfig 파일을 통해 제공하던 빌드 설정을 포함합니다.

After migration, you may need to add debug.xcconfig Xcode 프로젝트 구성에

모든 플러그인은 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 레이아웃을 가진 플러그인은 수동 작업이 필요합니다.

백업해야 하는 것들

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

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

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 템플릿 외부에서 추가한 원시 Swift, Objective-C, 프레임워크, 확장 또는 SDK 파일도 보존합니다.

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

iOS 프로젝트가 사용자 정의 원시 편집이 있는 경우 이 경로를 사용하세요. 편집을 유지하고 싶지 않다면.

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

bunx cap spm-migration-assistant

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

마이그레이션 어시스턴트가 완료되면 프로젝트를 열어주세요.

bunx cap open ios

그런 다음 어시스턴트가 출력하는 매뉴얼 Xcode 단계를 따르십시오. 대부분의 프로젝트에서 이것은 다음과 같습니다:

추가 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/ 이 경로를 사용할 때 Capacitor 디렉토리가 기본 템플릿과 가깝고 안전하게 커스텀 파일을 복원할 수 있는 경우 사용하십시오.

먼저 백업 섹션에 나열된 파일이 커밋되거나 안전한 곳에 복사되어 있는지 확인하십시오. 그런 다음 SPM을 사용하여 iOS 프로젝트를 다시 생성하십시오:

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 SPM

CI 업데이트하기

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

실행하지 않는 단계를 제거해주세요:

pod install

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

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

Keep your regular web build and Capacitor sync steps. A typical iOS job should install JavaScript dependencies, build the web assets, sync Capacitor, and then build with Xcode:

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

마이그레이션 체크리스트

이전 마이그레이션:

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

마이그레이션 중:

Run bunx cap spm-migration-assistant 또는 재구성 ios/.
Add CapApp-SPM Xcode에서 필요 시 추가
Add debug.xcconfig Xcode에서 필요할 경우.
__CAPGO_KEEP_0__을 복원합니다.
Run bunx cap sync ios.

이전으로의 마이그레이션 후:

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

문제 해결

Xcode에서 패키지 캐시를 초기화하고 다시 실행하여 패키지를 해결할 수 없으면 Xcode를 사용하세요. 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 For customized iOS projects, start with debug.xcconfig For projects close to the default template, a clean SPM re-scaffold is often faster and easier to reason about. pod install.

When the app builds locally but CI fails, check for old CocoaPods assumptions. bunx cap spm-migration-assistantCommon causes are a forced build path, a stale command, or caching from previous builds.

자원

How to Migrate a Capacitor App to Swift Package Manager로부터 계속 진행하세요

__CAPGO_KEEP_0__을 사용하고 있다면 Swift Package Manager로 Capacitor 앱을 마이그레이션하는 방법 이동 및 기업 운영을 계획하고 싶다면 __CAPGO_KEEP_0__ Enterprise와 연결하세요 Capgo Enterprise의 제품 워크플로우 for the product workflow in Capgo Enterprise, __CAPGO_KEEP_0__ Enterprise Ionic Enterprise 플러그인 대체 제품 workflow Capgo 대체 제품 Capgo 제품 workflow Capgo 컨설팅 Capgo 컨설팅 제품 workflow Capgo 프리미엄 지원 Capgo 프리미엄 지원 제품 workflow

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