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

Capacitor 8은 iOS 프로젝트를 기본적으로 스위프트 패키지 매니저(SPM)로 생성합니다. 아직 코코아팟을 사용하는 기존 앱도 마이그레이션할 수 있지만, 앱에 native iOS 커스텀화가 얼마나 많은지에 따라 가장 안전한 경로는 달라집니다.

이 가이드에서는 변경 사항, 백업해야 하는 항목, 두 가지 실제 마이그레이션 경로( Capacitor 마이그레이션 어시스턴트를 사용하거나 iOS 프로젝트를 SPM로 재구성하는 방법)에 대해 설명합니다.

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

코코아팟은 읽기 전용 트렁크 방향으로 이동하고 있습니다. 현재 계획은 2026년 12월 2일 코코아팟 트렁크가 새로운 podspec을 받지 않도록 하며, 기존 빌드는 계속 작동하지만, 새로운 릴리즈와 의존성 업데이트(트렁크에 의존하는 것)가 트렁크에 게시되지 않습니다. SPM은 __CAPGO_KEEP_0__도 향후 방향입니다. __CAPGO_KEEP_1__은 __CAPGO_KEEP_2__ 6부터 코코아팟 또는 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.

Capacitor 앱을 Swift로 마이그레이션하는 두 가지 방법

Capacitor 8은 iOS 프로젝트를 기본적으로 스위프트 패키지 매니저(SPM)로 생성합니다.

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 구성이 대체됩니다.

이동 보조 프로그램도 생성된

을 생성합니다. 이 파일은 CocoaPods가 생성한 xcconfig 파일을 통해 제공하던 빌드 설정을 포함합니다. debug.xcconfig이동 후, 보조 프로그램이 알려주신 대로 Xcode 프로젝트 구성에

을 추가해야 할 수 있습니다. debug.xcconfig 모든 플러그인은 SPM을 지원해야 합니다.

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

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의 __CAPGO_KEEP_1__을 사용하여 변환할 수 있지만 Objective-C와 Swift 레이아웃이 복잡한 플러그인은 수동 작업이 필요합니다. capacitor-plugin-converter어떤 것을 백업해야 하나요?

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

보존해야 하는 일반 파일

include: ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftCustom
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist파일
Custom .xcconfig 파일
설정

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

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

이 경로를 사용할 때 iOS 프로젝트에 사용자 지정 원본 편집이 포함되어 있습니다. 편집을 유지하고 싶습니다.

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

bunx cap spm-migration-assistant

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

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

bunx cap open ios

로컬 패키지를 프로젝트의 의존성으로 추가하십시오.

생성된 CapApp-SPM 앱 구성에 추가하십시오.
Add debug.xcconfig context
SPM으로 변환되지 않은 플러그인에 대한 경고를 해결하십시오.
Xcode에서 앱을 한 번 빌드한 후 CI를 업데이트하십시오.

Xcode 프로젝트가 빌드된 후 다시 싱크하십시오:

bunx cap sync ios

2. 옵션: iOS 프로젝트를 SPM으로 다시 구축하십시오.

디렉토리가 기본 __CAPGO_KEEP_0__ 템플릿과 유사하고 이후에 커스텀 파일을 복원할 수 있는 경우 사용하십시오. ios/ 디렉토리는 기본 Capacitor 템플릿과 가깝습니다. 이후 사용자 정의 파일을 안전하게 복원할 수 있습니다.

앱이 필요로 하는 네이티브 파일을 복원한 후 프로젝트를 열으십시오.

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

애플리케이션에 필요한 네이티브 파일을 복원한 후 프로젝트를 열어 주세요.

bunx cap open ios

새로운 Capacitor 앱

Capacitor 8에서 iOS를 추가할 때 기본적으로 SPM을 사용합니다.

Capacitor 8은 iOS에 대한 새 앱을 추가할 때 기본적으로 SPM을 사용합니다.

bunx cap add ios

SPM으로 변환되지 않은 플러그인에 대한 경고를 해결하십시오.

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

이동 중:

실행 bunx cap spm-migration-assistant 이동 후: ios/.
or 재구성 CapApp-SPM 추가
or 재구성 debug.xcconfig 추가
Xcode에서 필요 시 빌드하고 실행하세요.
실행 bunx cap sync ios.

앱에 특화된 네이티브 파일을 복원하세요.

이동 후:
iOS SPM과 Cocoapods와 Capgo 이관 가이드
제거 pod install CI에서
릴리즈 서명이 여전히 작동하는지 확인하세요.
최소한 한 개의 시뮬레이터와 한 개의 실제 기기에서 앱을 실행한 후에 배포하세요.

문제 해결

Xcode가 패키지를 해결할 수 없으면 Xcode에서 패키지 캐시를 초기화하고 실행하십시오. bunx cap sync ios again.

이전 버전의 Capgo 이관 가이드를 다시 읽어보세요.

이전 버전의 Capgo 이관 가이드를 다시 읽어보세요. .xcworkspace 이전 버전의 Capgo 이관 가이드를 다시 읽어보세요. pod install 앱이 로컬에서 빌드되지만 CI가 실패하면 오래된 Cocoapods 가정에 대해 확인하세요. 일반적인 원인은 강제된 빌드 경로, 오래된 명령, 또는 캐싱입니다. Pods/ 이전 빌드에서.

결론

Capacitor 앱을 Swift Package Manager로 이동하는 것은 iOS 의존성 연결을 대체하는 것에 대부분 있습니다. CapApp-SPM 의존성 참조를 대체하고, CocoaPods 빌드 구성이 생성되며, CI는 더 이상 debug.xcconfig 사용자 지정 iOS 프로젝트의 경우 시작하세요. pod install.

기본 템플릿과 가까운 프로젝트의 경우, 깨끗한 SPM 재구성은 더 빠르고 이해하기 쉬운 경우가 많습니다. bunx cap spm-migration-assistant자원

Resources

Swift Package Manager로 Capacitor 앱을 계속 진행하세요.

If you are using Capgo. Swift Package Manager로 Capacitor 앱을 이전하는 방법 migration과 기업 운영을 계획하고 연결하려면 __CAPGO_KEEP_0__ Enterprise Capgo 기업 Capgo Enterprise __CAPGO_KEEP_0__ Enterprise __CAPGO_KEEP_0__ Enterprise Capgo Enterprise Capgo Enterprise Capgo Enterprise Capgo Enterprise Capgo 프리미엄 지원 Capgo 프리미엄 지원을 위한 제품 워크플로우