beautifulsoups.dev
Published on

Flutter iOS 빌드 실패? pod install 오류 해결

Authors

Flutter로 iOS 빌드를 하다 보면 Xcode 자체보다 pod install 단계에서 먼저 무너지는 경우가 많습니다. 특히 팀 프로젝트나 CI 환경에서는 macOS/Xcode/CocoaPods/Ruby/Flutter 버전 조합이 조금만 달라도 같은 코드가 어떤 머신에서는 되고 어떤 머신에서는 깨집니다.

이 글은 "일단 빌드 되게" 하는 임시 처방이 아니라, 왜 pod install이 실패하는지를 로그 기준으로 분류하고, 가장 안전한 복구 순서(캐시 정리, Pods 재생성, Repo 갱신, Ruby 환경 정리, Xcode 설정 확인)를 제시합니다.

문제 해결 방식은 다른 디버깅과 동일합니다. 증상을 줄이고, 재현성을 높이고, 원인을 좁히는 과정이 핵심입니다. 이런 접근은 프론트엔드의 하이드레이션 문제를 좁힐 때도 유사합니다. 필요하면 Next.js Hydration mismatch 원인 7가지와 해결법처럼 “증상-원인-검증” 형태로 접근해 보세요.

pod install이 Flutter iOS 빌드에서 중요한 이유

Flutter의 iOS 네이티브 의존성은 CocoaPods가 관리합니다. flutter run 또는 Xcode 빌드 시 내부적으로 iOS 프로젝트의 Podfile을 기반으로 pod install이 수행되고, 그 결과로 Pods/, Podfile.lock, Runner.xcworkspace 등이 생성됩니다.

즉, iOS 빌드 실패의 상당수는 다음 중 하나입니다.

  • CocoaPods 자체가 실행 불가(루비/권한/경로)
  • Pod spec repo 동기화 문제
  • 특정 Pod 버전이 Xcode 또는 iOS Deployment Target과 충돌
  • Apple Silicon 환경에서 아키텍처/링커 문제
  • Flutter 플러그인이 요구하는 설정이 누락

먼저 확인할 것: 실패 지점을 정확히 잡기

Xcode에서만 빌드하면 로그가 묻히는 경우가 많습니다. 아래처럼 CLI로 먼저 실패 지점을 고정하세요.

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

cd ios
pod install --verbose

pod install --verbose 로그에서 다음 키워드를 찾으면 원인 분류가 빨라집니다.

  • CocoaPods could not find compatible versions for pod
  • Specs satisfying the ... dependency were found, but they required a higher minimum deployment target
  • CDN: trunk Repo update failed
  • ffi 또는 eventmachine 빌드 실패
  • Permission denied 또는 You don't have write permissions
  • ld: library not found 또는 Undefined symbols for architecture

가장 안전한 복구 순서(대부분 이걸로 해결)

여러 처방을 섞기 전에, 아래 순서를 그대로 실행해 보세요. "캐시 삭제"는 과하면 시간만 낭비하므로, iOS 폴더 범위부터 단계적으로 정리합니다.

1) Flutter 산출물 정리

flutter clean
flutter pub get

2) iOS Pods 재생성

cd ios
rm -rf Pods
rm -f Podfile.lock
rm -rf .symlinks
rm -rf Flutter/Flutter.framework Flutter/Flutter.podspec
pod install

여기서 pod install이 성공하면, Xcode에서는 반드시 Runner.xcworkspace를 열어야 합니다.

3) Pod repo 업데이트(네트워크/CDN 문제 포함)

cd ios
pod repo update
pod install

또는 설치 시점에만 업데이트를 강제하려면:

pod install --repo-update

대표 오류 1: Deployment Target이 낮아서 실패

로그 예시는 보통 이런 형태입니다.

  • required a higher minimum deployment target
  • Specs satisfying the ... dependency were found, but they required a higher minimum deployment target

해결은 Podfile의 플랫폼 버전을 올리는 것입니다.

# ios/Podfile
platform :ios, '13.0'

그 다음 재설치:

cd ios
pod install

추가로, Xcode 프로젝트의 Runner 타겟에서도 iOS Deployment Target이 동일하거나 더 높아야 합니다.

  • Xcode Runner 타겟 Build Settings에서 iOS Deployment Target 확인

팁: Flutter 플러그인 중 최신 버전은 iOS 12 이하를 더 이상 지원하지 않는 경우가 늘고 있습니다. 팀에서 지원 OS를 올릴 수 없다면 플러그인 버전 고정이 필요합니다.

대표 오류 2: Pod 버전 충돌(compatible versions 불가)

로그: CocoaPods could not find compatible versions for pod.

이 경우는 다음 중 하나입니다.

  • Podfile.lock에 고정된 버전이 새 플러그인 요구사항과 충돌
  • 특정 Pod가 다른 Pod와 상호 배타적 버전 제약

해결 체크리스트:

  1. Podfile.lock 삭제 후 재생성(앞의 "Pods 재생성" 단계)
  2. flutter pub upgrade로 Dart 의존성도 정렬
flutter pub upgrade
cd ios
rm -f Podfile.lock
pod install --repo-update
  1. 그래도 충돌하면, 어떤 Pod가 제약을 걸고 있는지 로그에서 의존성 체인을 확인하고 플러그인 버전을 조정합니다.

대표 오류 3: Apple Silicon(M1/M2)에서 ffi, eventmachine 설치 실패

CocoaPods는 Ruby gem에 의존합니다. Apple Silicon에서 ffi 같은 네이티브 확장 gem이 깨지면 pod install이 실패합니다.

권장 방향은 시스템 Ruby 대신 버전 매니저를 쓰는 것입니다.

rbenv 예시

brew install rbenv ruby-build
rbenv install 3.2.2
rbenv global 3.2.2

gem install cocoapods
pod --version

이미 설치된 gem이 꼬였으면:

gem uninstall cocoapods
gem install cocoapods

만약 회사 정책상 시스템 Ruby를 써야 한다면, 최소한 gem 설치 경로 권한 문제를 피하기 위해 sudo gem install 같은 방식은 지양하는 편이 좋습니다(환경이 쉽게 오염됩니다).

대표 오류 4: 권한 문제(Permission denied)

로그에 Permission denied가 보이면, 보통 다음 케이스입니다.

  • ~/.cocoapods 또는 gem 설치 디렉터리 권한 꼬임
  • 과거에 sudo pod install을 실행해서 생성물 소유자가 root로 바뀜

가장 흔한 복구는 ios 폴더 및 CocoaPods 캐시 권한을 사용자로 되돌리는 것입니다.

sudo chown -R "$(whoami)" ios
sudo chown -R "$(whoami)" ~/.cocoapods

그 다음 Pods 재생성:

cd ios
rm -rf Pods Podfile.lock
pod install

주의: 회사 보안 정책에 따라 sudo 사용이 제한될 수 있으니, 가능하면 Ruby 버전 매니저로 사용자 영역에 설치하는 쪽이 더 안전합니다.

대표 오류 5: Xcode 선택 문제(버전/경로)

Xcode를 여러 버전 설치한 경우, xcode-select가 다른 버전을 가리키면 pod install 또는 빌드가 실패할 수 있습니다.

xcode-select -p
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

또한 최초 설치 직후에는 라이선스 동의가 필요합니다.

sudo xcodebuild -license accept

대표 오류 6: Runner.xcworkspace가 아닌 Runner.xcodeproj를 열어서 실패

Pods가 정상 설치돼도 Xcode에서 Runner.xcodeproj로 열면 Pods 타겟이 연결되지 않아 빌드가 실패합니다.

  • 항상 ios/Runner.xcworkspace를 열기

이 문제는 단순하지만 팀 온보딩에서 자주 반복됩니다. README에 명시해 두는 걸 추천합니다.

대표 오류 7: 네트워크/CDN 문제로 spec 다운로드 실패

로그에 CDN: trunk Repo update failed 또는 다운로드 타임아웃이 보이면:

  • 사내 프록시/VPN
  • 방화벽
  • 일시적인 CocoaPods CDN 장애

대응:

cd ios
pod install --repo-update --verbose

그래도 안 되면 네트워크를 바꿔 재시도하거나, CI에서는 캐시된 Pods를 활용하는 전략을 고려하세요.

CI에서 재발 방지: 버전 고정과 재현성 확보

로컬에서만 고치면 CI에서 다시 터지는 경우가 많습니다. 재발 방지를 위해 아래를 권장합니다.

1) Flutter 버전 고정

fvm을 사용하면 팀 전체 Flutter SDK 버전을 고정할 수 있습니다.

dart pub global activate fvm
fvm install 3.19.6
fvm use 3.19.6
fvm flutter --version

2) CocoaPods 버전 고정

프로젝트에 Gemfile을 두고 Bundler로 CocoaPods를 고정하면 머신별 편차가 줄어듭니다.

# ios/Gemfile
source 'https://rubygems.org'

gem 'cocoapods', '1.15.2'

설치 및 실행:

cd ios
bundle install
bundle exec pod install

3) 문제 해결 로그를 남기는 습관

pod install 실패는 “환경 이슈”로 뭉뚱그리기 쉽지만, 실제로는 로그 한 줄에 원인이 드러납니다. 장애 추적을 체계화하는 습관은 다른 영역에서도 큰 도움이 됩니다. 예를 들어 런타임 호환성 문제를 파고드는 방식은 Bun 1.1에서 Node API 호환이 깨질 때 디버깅 같은 케이스와도 유사합니다.

자주 묻는 체크리스트(최소 커맨드 세트)

아래는 “오늘 당장 빌드해야 하는데 pod install이 깨졌다” 상황에서의 최소 세트입니다.

flutter clean
flutter pub get

cd ios
rm -rf Pods Podfile.lock .symlinks
pod install --repo-update

여기까지 실패하면, 다음을 추가 확인합니다.

xcodebuild -version
xcode-select -p
ruby -v
pod --version

그리고 로그에서 deployment target, compatible versions, ffi, permission denied, CDN 중 어떤 패턴인지 먼저 분류한 뒤 위 섹션의 처방을 적용하세요.

마무리

Flutter iOS 빌드에서 pod install 오류는 대개 “CocoaPods가 이상해요”가 아니라, 버전 제약, 타겟 버전, Ruby 환경, 권한, 네트워크 중 하나로 귀결됩니다.

  • 먼저 pod install --verbose로 실패 지점을 고정
  • Pods와 Podfile.lock를 재생성해 의존성 상태를 리셋
  • iOS Deployment Target과 Xcode 버전을 맞춤
  • Apple Silicon이라면 Ruby 환경을 정리하고 CocoaPods를 고정

원하시면, 실제 에러 로그(전체 말고 핵심 20~40줄)와 Podfile의 platform 줄만 공유해 주시면, 해당 케이스에 맞춰 가장 짧은 해결 경로로 정리해 드릴게요.

Discuss on Twitter • View on GitHub