Capacitor 8에서 CocoaPods를 사용하는 방법 (그리고 쓰지 말아야 할 때)

Capacitor 8에서 CocoaPods를 사용하려면, 다음 명령어로 iOS 플랫폼을 생성하고 bunx cap add ios --packagemanager CocoaPods, CocoaPods를 설치(Homebrew 또는 Bundler를 사용한 Gemfile)한 뒤 bunx cap sync ios Podfile을 관리하고 실행하려면 pod install. Capacitor 8에서도 CocoaPods를 완벽하게 지원합니다. 새로운 프로젝트의 기본 설정만 Swift Package Manager로 변경되었습니다.

CocoaPods는 더 이상 장기적인 방향이 아니며, 2026년 12월 2일에 trunk가 읽기 전용으로 전환됩니다. 따라서 핵심은 언제 CocoaPods가 여전히 올바른 선택인지, 어떻게 계속 작동하게 유지할지, 그리고 어떻게 깔끔하게 전환할지입니다. 이 가이드에서 이 세 가지를 모두 다룹니다.

CocoaPods가 여전히 올바른 선택인 경우

다음 중 하나라도 해당된다면 CocoaPods를 계속 사용하거나 선택하세요:

• 필요한 플러그인에 Package.swift. SPM 프로젝트에서 CLI는 “Some installed Capacitor plugins are not compatible with SPM”라는 경고를 띄우며 해당 플러그인을 제외하므로, 런타임 시 “plugin is not implemented” 오류가 발생합니다.
• 벤더 SDK가 pod로만 배포되는 경우. 일부 분석, 결제 및 인증 SDK는 여전히 CocoaPods만 지원하거나, 직접 래핑해야 하는 xcframework 형태로 제공됩니다.
• Cordova 플러그인이 pods에 의존하는 경우. Capacitor는 SPM 프로젝트의 Cordova 플러그인을 위한 Swift package를 생성하지만, 의존성이 복잡한 경우 <podspec> CocoaPods를 사용하는 것이 더 안정적입니다.
• podspec subspec에 의존하는 경우 SDK 변형을 선택하기 위해서입니다. 이제 SPM에는 package traits가 있고, Capacitor은 CLI 8.3부터 이를 실험적으로 지원합니다(참조: Capacitor의 SPM package traits), 다만 플러그인이 먼저 traits를 정의해야 합니다.
• 대규모 커스텀 Xcode 프로젝트 이번 릴리스 주기에는 마이그레이션 리스크가 너무 큰 경우입니다.

패키지 ID 충돌도 예전에는 또 하나의 이유였습니다. CLI 8.4부터는 SPM에서 다음 방법으로 우회할 수 있습니다 experimental.ios.spm.packageOptions (symlink 또는 moduleAliases)를 Capacitor 설정에 추가하면 됩니다.

위 항목에 해당하지 않는다면 SPM을 사용하세요. Ruby 툴체인도, Podfile도, 그리고 .xcworkspace.

Capacitor 8에서의 CocoaPods vs SPM

CocoaPods 설치

한 가지 방식을 선택하여 CI를 포함한 모든 곳에 적용하세요.

Homebrew (개인 개발자에게 가장 간단함):

brew install cocoapods
pod --version

Bundler (팀 전체의 버전을 고정하므로 CI에 권장됨). 다음을 생성하세요: Gemfile 프로젝트 루트 또는 ios/App:

source 'https://rubygems.org'
gem 'cocoapods', '~> 1.16'

bundle install

Capacitor CLI가 다음을 찾으면 Gemfile CocoaPods를 언급하는 항목을 실행합니다 bundle exec pod install 를 전달하고 pod install. 만약 pod 가 일반적이지 않은 위치에 있다면, CAPACITOR_COCOAPODS_PATH 를 바이너리로 설정하세요

CocoaPods로 Capacitor 8 앱 만들기

bun add @capacitor/ios
bun run build
bunx cap add ios --packagemanager CocoaPods
bunx cap open ios

cap open ios 가 열립니다 App.xcworkspace. 항상 워크스페이스에서 빌드하세요. App.xcodeproj 를 직접 열면 No such module 'Capacitor'.

Podfile 완벽 가이드

다음은 Podfile Capacitor 8이 생성하는 내용입니다:

require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'

platform :ios, '15.0'
use_frameworks!

install! 'cocoapods', :disable_input_output_paths => true

def capacitor_pods
  pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
end

target 'App' do
  capacitor_pods
  # Add your Pods here
end

post_install do |installer|
  assertDeploymentTarget(installer)
end

수정 가능한 범위와 불가능한 범위:

• def capacitor_pods ... end CLI의 소유입니다. 동기화할 때마다 해당 블록 전체를 플러그인당 pod 한 줄로 교체하며, 플러그인의 폴더를 node_modules가리킵니다. 이 안에 직접 추가한 내용은 삭제됩니다.
• 다음 항목 아래에 직접 pod를 추가하세요: target 'App'이는 capacitor_pods.
• assertDeploymentTarget 배포 타겟이 15.0 미만인 모든 pod를 15.0으로 상향 조정하여 Xcode의 지원되지 않는 타겟 경고를 방지합니다. 이 설정은 유지하고, 직접 추가할 pod는 post_install 동일한 블록 내에 로직을 작성하세요.
• platform :ios Capacitor 8을 사용하려면 최소 15.0이어야 합니다.

추가 pod 및 빌드 설정 수정 예시:

target 'App' do
  capacitor_pods
  pod 'GoogleMLKit/BarcodeScanning', '~> 7.0'
end

post_install do |installer|
  assertDeploymentTarget(installer)
  installer.pods_project.targets.each do |target|
    if target.respond_to?(:product_type) && target.product_type == 'com.apple.product-type.bundle'
      target.build_configurations.each do |config|
        config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
      end
    end
  end
end

이 루프는 리소스 번들 타겟에 대한 code 서명을 비활성화합니다. 이는 Signing for "X" requires a development team 리소스 번들을 포함하는 pod의 경우입니다. 해당 에러가 발생할 때만 추가하세요.

자주 사용하는 명령어

# After installing or removing a plugin
bunx cap sync ios

# Use the exact versions in Podfile.lock (good for CI)
bunx cap sync ios --deployment

# Refresh the spec repo when a new pod version isn't found
cd ios/App && pod repo update && pod install

# Update one pod past its locked version
cd ios/App && pod update FirebaseMessaging

cap sync ios 또한 실행됩니다 xcodebuild clean 이후 프로젝트에서 pod install, 따라서 플러그인을 추가한 뒤 수동으로 clean할 필요가 없습니다.

Commit Podfile 및 Podfile.lock. 다음은 commit하지 마세요 ios/App/Pods/. It’s regenerated by pod install.

기존 앱을 SPM에서 CocoaPods로 전환하기

역마이그레이션 명령어는 없습니다. 직접 수행하세요:

1. Commit한 후 복사하세요 ios/ 안전한 곳에 보관하세요.
2. 삭제 ios/.
3. 실행 bunx cap add ios --packagemanager CocoaPods.
4. 네이티브 변경 사항 재적용: Info.plist keys, entitlements 및 capabilities, signing team, bundle identifier, app icons 및 splash assets, URL schemes, extensions (widgets, notification service), 그리고 모든 커스텀 Swift code AppDelegate.
5. bunx cap sync ios 및 빌드하세요.

이전 버전과 새 버전의 차이점을 ios/App/App 폴더를 비교하는 것이 놓친 부분을 찾는 가장 빠른 방법입니다.

자주 발생하는 CocoaPods 오류 해결법

CocoaPods could not find compatible versions for pod "X". 로컬 spec repo가 오래되었거나 두 개의 pod이 서로 호환되지 않는 버전을 요구하고 있습니다. 다음을 실행하세요: pod install --repo-update 에서 ios/App. 그래도 실패한다면 에러 메시지의 의존성 체인을 확인하여 버전을 엄격하게 고정(strict pin)한 플러그인을 찾아 업그레이드하거나 podspec 패치하기.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. 이 Pods 폴더가 lock 파일과 일치하지 않습니다. 보통 브랜치를 전환한 후에 발생합니다. 다음 명령어를 실행하세요: bunx cap sync ios.

[!] Unable to find a specification for 'X'. spec repo 캐시가 오래되었거나 pod 이름이 잘못되었습니다. 다음 명령어를 실행하세요: pod repo update.

Unable to find compatibility version string for object version '70' (또는 77). Xcode 프로젝트 형식이 현재 설치된 CocoaPods/xcodeproj gem 버전보다 최신입니다. CocoaPods를 최신 버전으로 업데이트하세요. 업데이트가 불가능하다면, 기존 데이터를 백업한 뒤 project.pbxproj 그리고 설정하세요. objectVersion CocoaPods가 지원하는 버전으로 되돌리세요.

Sandbox: rsync(...) deny(1) file-write-create. Xcode의 User Script Sandboxing 설정이 CocoaPods의 embed script를 차단하고 있습니다. 빌드 설정에서 User Script 샌드박싱 (ENABLE_USER_SCRIPT_SANDBOXING)을 아니요 App 타겟용입니다.

No such module 'Capacitor'. 열었습니다 App.xcodeproj. App.xcworkspace, 또는 bunx cap open ios.

pod: command not found CI에서 실행하세요. 작업에 CocoaPods를 설치하거나, 캐시된 Bundler를 사용하세요. vendor/bundle. 그렇지 않으면 CLI에 “Skipping pod install because CocoaPods is not installed”라는 로그가 남고 이후 빌드가 실패합니다.

기타 iOS 빌드 오류는 다음에서 확인할 수 있습니다: Capacitor iOS 트러블슈팅 가이드.

CocoaPods trunk 읽기 전용 날짜

CocoaPods 유지관리자들은 2026년 11월 초 테스트를 거쳐 2026년 12월 2일부터 중앙 스펙 저장소인 trunk가 읽기 전용으로 전환된다고 발표했습니다. Capacitor 앱에 미치는 영향은 다음과 같습니다:

• 기존 빌드는 계속 작동합니다. 이미 게시된 모든 podspec은 계속 사용할 수 있습니다.
• trunk로는 새 버전을 배포할 수 없습니다. trunk에서 가져오는 SDK(Firebase, Google ML Kit, 벤더 SDK)는 더 이상 업데이트를 받지 못합니다. 보안 수정과 새로운 iOS SDK 지원은 SPM 등 다른 채널로만 제공됩니다.
• Capacitor 플러그인 자체는 직접적인 영향을 받지 않습니다. 플러그인은 npm에서 설치되고 :path Podfile에서 참조됩니다. 이들의 전이적 pod 의존성은 영향을 받습니다.

CocoaPods는 과도기적 도구로 보고, 어떤 의존성 때문에 계속 쓰고 있는지 정리해 두었다가 해당 의존성이 SPM을 지원하면 다시 검토하세요.

CocoaPods에서 벗어나기

준비가 되었다면:

bunx cap spm-migration-assistant

실행: pod deintegrate, 를 제거하고 Podfile, Podfile.lock 및 App.xcworkspace, 를 생성하며 CapApp-SPM, 를 작성합니다. 그런 다음 debug.xcconfig를 추가합니다. CapApp-SPM 를 Xcode의 로컬 패키지로 추가하고 debug.xcconfig 를 Debug 설정 파일로 지정합니다. 전체 가이드는 Capacitor 앱을 SPM으로 마이그레이션하는 방법을에서 확인할 수 있으며, 장단점은 Capacitor를 위한 SPM vs CocoaPods 비교.

에서 다룹니다. SPM 지원을 추가해야 하는 플러그인 개발자는 Capacitor 플러그인을 SPM으로 마이그레이션.

빌드 머신에서 Ruby, CocoaPods, Xcode 버전을 관리하는 것이 번거롭다면, Capgo 빌드 최신 Xcode를 사용하여 클라우드에서 CocoaPods 및 SPM 프로젝트를 빌드합니다.