beautifulsoups.dev
Published on

Flutter iOS 빌드 실패? CocoaPods 오류 7가지

Authors

Flutter로 iOS 빌드를 하다 보면, 실제 컴파일 에러보다 pod install 단계에서 막히는 경우가 훨씬 많습니다. 특히 팀 개발 환경에서 Xcode, Ruby, CocoaPods, iOS 최소 타깃, 아키텍처 설정이 조금만 어긋나도 같은 프로젝트가 어떤 맥에서는 되고 어떤 맥에서는 깨집니다.

이 글은 Flutter iOS 빌드 실패를 유발하는 CocoaPods 관련 오류를 7가지로 묶어서, 증상 로그 패턴과 원인, 해결 커맨드, 재발 방지 체크리스트까지 한 번에 정리합니다.

참고: iOS 빌드 실패는 네트워크나 레이트리밋 같은 외부 요인도 섞여 나타납니다. 재시도와 백오프 설계 관점은 OpenAI API 429 재시도·백오프 패턴 실전 가이드도 함께 보면 문제를 더 구조적으로 분리하는 데 도움이 됩니다.

공통 진단 루틴 (문제별 해결 전에 먼저)

아래 순서만 지켜도, 원인 범위를 절반 이상 줄일 수 있습니다.

1) Flutter, Xcode, CocoaPods 버전 확인

flutter --version
xcodebuild -version
pod --version
ruby -v

2) 캐시 및 Pod 아티팩트 정리

flutter clean
rm -rf ios/Pods ios/Podfile.lock ios/.symlinks
rm -rf ~/Library/Developer/Xcode/DerivedData

3) iOS 디렉터리에서 재설치

cd ios
pod repo update
pod install --verbose

4) Apple Silicon 여부 확인 (M1, M2, M3)

uname -m

arm64면 아키텍처 이슈가 섞일 수 있습니다.

오류 1) CocoaPods could not find compatible versions for pod ...

대표 증상

  • CocoaPods could not find compatible versions for pod "FirebaseCore" 같은 메시지
  • Podfile.lock에 고정된 버전과 플러그인이 요구하는 버전이 충돌

원인

  • 플러그인 업데이트로 의존 Pod 최소 버전이 상승했는데, Podfile.lock이 오래된 버전을 고정
  • 여러 Flutter 플러그인이 같은 Pod를 서로 다른 범위로 요구

해결 절차

  1. 락 파일 제거 후 재해결
rm -f ios/Podfile.lock
rm -rf ios/Pods
cd ios
pod install
  1. 그래도 충돌하면 pod update로 특정 Pod만 업데이트
cd ios
pod update FirebaseCore --no-repo-update
  1. Flutter 플러그인 버전 정리
flutter pub outdated
flutter pub upgrade

재발 방지

  • 팀에서는 Podfile.lock 커밋 여부를 정책으로 통일
  • 플러그인 대규모 업데이트 시 iOS 빌드 파이프라인에서 pod install을 깨끗한 상태에서 검증

오류 2) Specs satisfying the ... dependency were found, but they required a higher minimum deployment target

대표 증상

  • required a higher minimum deployment target 문구
  • 예: iOS 11로 설정했는데 어떤 Pod는 iOS 12 이상 요구

원인

  • platform :ios, '11.0'가 낮게 설정됨
  • Flutter 플러그인 또는 최신 Firebase, gRPC, GoogleUtilities 등이 iOS 최소 타깃을 올림

해결 절차

  1. ios/Podfile의 platform을 상향
platform :ios, '12.0'
  1. Xcode 프로젝트의 Deployment Target도 함께 맞추기
  • Xcode에서 Runner 타깃 선택
  • Build Settings에서 iOS Deployment Target을 Podfile과 동일하게
  1. Pods 재설치
rm -rf ios/Pods ios/Podfile.lock
cd ios
pod install

재발 방지

  • CI에서 xcodebuild -showBuildSettings로 실제 Deployment Target을 출력해 drift를 조기에 발견

오류 3) pod: command not found 또는 Ruby 관련 설치 실패

대표 증상

  • pod: command not found
  • You don't have write permissions for the /Library/Ruby/Gems/... 같은 권한 오류

원인

  • CocoaPods 미설치
  • 시스템 Ruby에 gem을 설치하려다 권한 문제
  • rbenv, rvm, asdf 등 Ruby 버전 매니저와 충돌

해결 절차 (권장: Homebrew 기반)

  1. CocoaPods 설치
brew install cocoapods
pod setup
  1. 이미 gem으로 설치되어 꼬였으면 정리 후 재설치
gem uninstall cocoapods
brew reinstall cocoapods
  1. PATH 확인
which pod
pod --version

재발 방지

  • 팀 온보딩 문서에 brew install cocoapods를 표준으로 통일
  • Ruby 버전 매니저를 쓰는 팀이라면 .ruby-version까지 포함해 일관성 확보

오류 4) ffi / nokogiri 네이티브 확장 빌드 실패 (특히 Apple Silicon)

대표 증상

  • ERROR: Failed to build gem native extension
  • ffi 또는 nokogiri 설치 단계에서 실패

원인

  • Ruby gem 네이티브 확장 모듈이 현재 Ruby 및 macOS SDK와 맞지 않음
  • Apple Silicon에서 x86_64로 설치된 Ruby 또는 반대 조합

해결 절차

  1. 현재 아키텍처와 Ruby 아키텍처 정합성 확인
uname -m
ruby -v
file "$(which ruby)"
  1. Homebrew Ruby 사용 시 재설치
brew reinstall ruby
  1. 문제가 지속되면 CocoaPods를 Rosetta로 실행하는 임시 우회
arch -x86_64 pod install
  1. 또는 터미널 자체를 Rosetta로 열어 동일 조건 유지

재발 방지

  • Apple Silicon에서는 arm64로 도구 체인을 맞추는 것을 1순위로 두고, Rosetta는 최후의 우회로만 사용

오류 5) The sandbox is not in sync with the Podfile.lock

대표 증상

  • sandbox is not in sync with the Podfile.lock 메시지
  • 로컬에서는 되다가 브랜치 변경 후 갑자기 실패

원인

  • Pods/Manifest.lock와 Podfile.lock 불일치
  • Pods 디렉터리 일부만 남아 있는 상태

해결 절차

cd ios
rm -rf Pods
rm -f Podfile.lock
pod install

추가로 Xcode 워크스페이스를 열고 있는 상태에서 충돌이 반복되면 Xcode 종료 후 다시 시도하세요.

재발 방지

  • 브랜치 이동 시 Podfile.lock 변경이 있는지 확인
  • CI에서 pod install 결과가 깨끗한지 검증

오류 6) Multiple commands produce ... 또는 중복 리소스/프레임워크 충돌

대표 증상

  • Multiple commands produce로 시작하는 빌드 에러
  • 같은 번들 리소스, 프레임워크가 두 번 복사되는 문제

원인

  • 플러그인이 추가되며 동일 리소스가 서로 다른 타깃/빌드 단계에 중복 등록
  • 오래된 Pods 캐시와 새 설정이 섞임

해결 절차

  1. DerivedData 및 Pods 정리
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ios/Pods ios/Podfile.lock
cd ios
pod install
  1. Xcode에서 Build Phases 확인
  • Runner 타깃의 Copy Bundle Resources
  • Embed Frameworks

중복 항목이 있으면 하나를 제거합니다.

  1. Flutter 플러그인 중복 의존 확인
flutter pub deps

재발 방지

  • 플러그인 대량 추가 후에는 iOS 빌드를 한 번 깨끗한 환경에서 재검증

오류 7) 네트워크/레포 문제: pod repo update가 느리거나 실패, CDN 이슈

대표 증상

  • pod install이 오래 걸리다가 실패
  • CDN: trunk Repo update failed 같은 로그

원인

  • CocoaPods trunk CDN 접근 문제
  • 회사 네트워크 프록시, 방화벽, DNS 이슈
  • 일시적인 레이트리밋 또는 GitHub 접근 불안정

해결 절차

  1. 레포 업데이트를 분리하고, 설치는 업데이트 없이 시도
cd ios
pod repo update
pod install --no-repo-update
  1. 네트워크가 불안정하면 재시도 전략을 명시적으로 적용
for i in 1 2 3; do
  pod install --no-repo-update && break
  sleep $((i*5))
done
  1. DNS나 프록시가 의심되면, 동일 네트워크에서 다른 레포 접근도 확인
  • curl -I https://cdn.cocoapods.org/

재발 방지

문제를 빠르게 좁히는 체크리스트

아래 항목은 실제로 Flutter iOS 빌드 실패를 가장 빨리 수습하게 해주는 순서입니다.

  1. ios/Podfile의 platform :ios가 현재 플러그인 요구사항보다 낮지 않은가
  2. Podfile.lock이 오래되어 플러그인 요구 버전과 충돌하지 않는가
  3. Apple Silicon에서 arm64와 x86_64가 섞여 있지 않은가
  4. CocoaPods 설치 경로가 두 개 이상 존재하지 않는가 (which pod로 확인)
  5. DerivedData, Pods, Podfile.lock을 모두 비운 뒤에도 재현되는가
  6. 네트워크 이슈가 섞여 있는가 (특히 pod repo update 단계)

자주 쓰는 복구 스크립트 (로컬에서 안전하게)

아래는 iOS Pod 환경을 “초기화에 가깝게” 되돌리는 커맨드 묶음입니다.

flutter clean
rm -rf ~/Library/Developer/Xcode/DerivedData
rm -rf ios/Pods ios/Podfile.lock ios/.symlinks
cd ios
pod repo update
pod install --verbose
cd ..
flutter build ios --debug

마무리

CocoaPods 오류는 대부분 “설치 상태 불일치”에서 출발합니다. 따라서 해결의 핵심은 특정 에러 메시지만 보고 땜질하기보다, 버전 고정 파일(Podfile.lock), iOS 최소 타깃, 아키텍처(arm64/x86_64), 네트워크를 축으로 원인을 분리하는 것입니다.

다음 단계로는, 팀 환경에서 재발을 줄이기 위해 CI에서 pod install을 항상 깨끗한 워크스페이스에서 실행하고, 실패 로그를 pod install --verbose로 남겨 비교 가능하게 만드는 것을 권장합니다.

Discuss on Twitter • View on GitHub