beautifulsoups.dev
Published on

Flutter iOS 빌드 실패? CocoaPods 오류 해결

Authors

서버·웹보다 모바일 빌드는 로컬 환경 의존성이 훨씬 큽니다. Flutter iOS 빌드가 실패할 때도 대부분 Dart 코드 문제가 아니라 CocoaPods/Xcode/아키텍처/캐시가 얽힌 환경 문제로 터집니다. 특히 pod install 단계에서 에러가 나면 로그가 길고 원인이 여러 갈래라서, 무작정 clean만 반복하다 시간을 쓰기 쉽습니다.

이 글은 Flutter iOS 빌드 실패를 CocoaPods 오류 중심으로 분류하고, “무엇부터 확인해야 하는지”를 재현 가능한 순서로 정리한 실전 가이드입니다. 빌드 파이프라인에서 원인 분리가 중요하다는 점은 다른 장애 대응과 동일합니다. 예를 들어 Docker 빌드가 느릴 때 - BuildKit 캐시 깨짐 해결처럼 캐시가 문제의 핵심이 되는 경우가 많습니다.

1) 먼저 확인: Flutter가 아니라 Xcode/CocoaPods 문제인가?

가장 먼저 할 일은 Flutter 레이어를 걷어내고, iOS 네이티브 빌드가 가능한지 확인하는 것입니다.

  1. Flutter 빌드 로그에서 Running pod install... 이후 실패하는지 확인
  2. ios 폴더에서 직접 pod install 실행
  3. Xcode에서 .xcworkspace로 열어 빌드

아래 명령으로 1차 분리합니다.

cd ios
pod --version
pod install --verbose
  • pod install 자체가 실패하면 CocoaPods/Ruby/Repo/Podspec 문제
  • pod install은 성공하지만 Xcode 빌드가 실패하면 Signing/Build Settings/아키텍처 문제
  • 둘 다 성공인데 flutter build ios만 실패하면 Flutter 툴체인/플러그인 설정/Generated 파일 문제

2) 가장 흔한 해결 루틴: 캐시·Pods·Lock을 깨끗이 정리

CocoaPods 오류의 상당수는 Pods 캐시나 Podfile.lock이 현재 상태와 어긋나서 납니다. 다음 루틴은 “일단 환경을 새로 맞추는” 데 효과적입니다.

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

추가로, CocoaPods CDN/Specs가 꼬인 경우 아래도 도움이 됩니다.

pod cache clean --all

주의할 점:

  • pod repo update는 시간이 오래 걸릴 수 있지만, 오래된 Specs 때문에 특정 버전이 해석되지 않는 경우를 해결합니다.
  • DerivedData 제거는 Xcode 인덱스/빌드 산출물 꼬임을 제거합니다.

3) .xcodeproj로 열어서 실패하는 실수: 반드시 .xcworkspace

CocoaPods를 쓰는 iOS 프로젝트는 Xcode에서 반드시 Runner.xcworkspace로 열어야 합니다. .xcodeproj로 열면 Pods가 링크되지 않아 다음과 같은 오류가 납니다.

  • Framework not found Pods_Runner
  • ld: library not found for -lPods-Runner

해결:

  • Xcode 종료
  • ios/Runner.xcworkspace로 다시 열기
  • Product 메뉴에서 Clean Build Folder 실행

4) 최소 iOS 버전 불일치로 Pod가 설치 실패하는 경우

플러그인이 요구하는 최소 iOS 버전이 올라가면, pod install에서 아래처럼 실패할 수 있습니다.

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

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

platform :ios, '13.0'

그리고 Flutter 쪽에서도 ios/Runner.xcodeproj의 iOS Deployment Target이 같은 값 이상인지 확인합니다.

빌드가 “갑자기” 깨졌다면 최근에 추가/업데이트한 플러그인의 릴리즈 노트를 확인하세요. iOS 최소 버전 상향은 흔한 변경입니다.

5) Apple Silicon(M1/M2/M3)에서 아키텍처 문제로 실패

Apple Silicon 환경에서 시뮬레이터 빌드가 실패하며 다음과 같은 키워드가 보이면 아키텍처 이슈일 가능성이 큽니다.

  • building for iOS Simulator, but linking in object file built for iOS
  • arm64 관련 링크 오류

대응 방법은 상황별로 다릅니다.

5-1) CocoaPods/Xcode/Flutter 최신화

가장 안정적인 방법은 툴체인을 최신 조합으로 맞추는 것입니다.

flutter upgrade
sudo gem install cocoapods
pod --version

5-2) 시뮬레이터에서만 arm64 제외(임시 처방)

일부 레거시 바이너리 Pod가 시뮬레이터 arm64를 지원하지 않을 때, Podfile에서 시뮬레이터 빌드에 한해 제외할 수 있습니다.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
    end
  end
end

주의:

  • 이건 근본 해결이 아니라 “빌드를 통과시키는” 우회입니다.
  • 가능하면 해당 Pod/플러그인을 arm64 simulator 지원 버전으로 올리는 게 정석입니다.

6) use_frameworks! / use_modular_headers! 충돌

Flutter 플러그인 조합에 따라 다음과 같은 헤더/모듈 오류가 발생합니다.

  • Include of non-modular header inside framework module
  • Module not found

이때 Podfile의 설정이 원인이 되는 경우가 많습니다.

6-1) use_frameworks!를 켜야 하는 경우

Swift 기반 Pod가 있고 정적 링크로 해결이 안 되면 다음이 필요할 수 있습니다.

use_frameworks! :linkage => :static
use_modular_headers!

다만 모든 조합에서 정답은 아니고, 플러그인 요구사항에 따라 달라집니다. 특정 플러그인이 use_frameworks!와 충돌하는 케이스도 있으니, 에러 로그에서 문제가 되는 Pod 이름을 먼저 특정한 뒤 적용하세요.

7) pod install이 Ruby/openssl/ffi에서 깨지는 경우

macOS 업데이트 후 Ruby 환경이 꼬이면 CocoaPods가 아래처럼 터질 수 있습니다.

  • ffi 빌드 실패
  • openssl 관련 로드 실패
  • activesupport 버전 충돌

이런 경우는 “iOS 프로젝트 문제”가 아니라 “로컬 Ruby/CocoaPods 런타임 문제”입니다. 해결 방향은 2가지입니다.

7-1) Homebrew Ruby 사용(권장)

시스템 Ruby 대신 brew Ruby를 쓰면 안정적인 편입니다.

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
ruby -v
gem install cocoapods
pod --version

7-2) Bundler로 CocoaPods 버전 고정

팀 개발에서 특히 유용합니다. ios/Gemfile을 만들고 CocoaPods 버전을 고정합니다.

source 'https://rubygems.org'

gem 'cocoapods', '1.15.2'

설치 및 실행:

cd ios
bundle install
bundle exec pod install

이렇게 하면 “내 컴퓨터만 빌드가 안 됨” 같은 환경 편차가 줄어듭니다. 장애가 환경 의존적으로 재현될 때는 원인 분리가 핵심인데, 이 접근은 CI에서도 동일하게 통합니다. 비슷한 맥락으로 Jenkins 에이전트 오프라인 원인·복구 10분처럼 실행 환경을 표준화하는 게 장기적으로 비용을 줄입니다.

8) Xcode 빌드 설정과 CocoaPods 연동 이슈 체크리스트

CocoaPods는 설치가 성공해도 Xcode 빌드에서 터질 수 있습니다. 아래는 자주 놓치는 항목입니다.

  • Xcode에서 Runner 타겟의 Signing & Capabilities가 올바른지
  • Build Settings에서 Swift Language Version이 플러그인 요구사항과 충돌하지 않는지
  • Other Linker Flags에 이상한 값이 들어가 있지 않은지
  • ENABLE_BITCODE는 최신 iOS에서는 보통 필요 없으며, 레거시 설정이 충돌을 만들 수 있음

문제가 발생하면 “Flutter 빌드”로만 보지 말고, Xcode의 Report navigator에서 실패 지점을 확인하세요. CocoaPods 관련이면 보통 CompileC, Ld, PhaseScriptExecution 단계에서 힌트가 나옵니다.

9) CI에서만 실패할 때: Pod 캐시/Repo 업데이트 전략

로컬에서는 되는데 CI에서만 pod install이 실패한다면 다음을 의심합니다.

  • CocoaPods Specs 업데이트가 안 되어 있음
  • Pod 캐시가 깨져 있음
  • Xcode 버전이 로컬과 다름

CI에서는 다음 중 하나로 안정화합니다.

  • pod repo update를 주기적으로 수행하거나, 최소한 실패 시 재시도
  • Podfile.lock을 커밋하고 pod install이 동일 버전을 쓰도록 강제
  • 가능하면 bundle exec pod install로 CocoaPods 버전 고정

빌드 캐시 전략이 성능과 안정성에 동시에 영향을 준다는 점은 인프라 쪽 이슈와도 유사합니다. 예를 들어 Argo CD Sync 실패 - OutOfSync·Degraded 해결처럼 “상태 불일치”가 문제를 만든다는 점에서 원리가 같습니다.

10) 문제를 빨리 끝내는 디버깅 순서(추천)

마지막으로, 시간을 아끼는 순서를 정리합니다.

  1. ios/Runner.xcworkspace로 열었는지 확인
  2. cd ios && pod install --verbose로 CocoaPods 단에서 재현
  3. 클린 루틴 실행: Pods, Podfile.lock, DerivedData 제거 후 재설치
  4. 최소 iOS 버전 상향 필요 여부 확인
  5. Apple Silicon 아키텍처 이슈 여부 확인(arm64 키워드)
  6. Ruby/CocoaPods 런타임 문제면 brew Ruby 또는 Bundler로 고정
  7. 그래도 안 되면 실패 로그에서 “첫 번째 에러”가 발생한 Pod 이름을 기준으로 해당 Pod/플러그인 이슈 트래킹

부록) 자주 쓰는 명령 모음

# Flutter 산출물 정리
flutter clean

# iOS Pod 재설치 루틴
rm -rf ios/Pods ios/Podfile.lock ios/.symlinks
cd ios
pod deintegrate
pod repo update
pod install

# Xcode 캐시 정리
rm -rf ~/Library/Developer/Xcode/DerivedData

CocoaPods 오류는 “한 방에 해결”보다 원인 분리가 핵심입니다. 위 순서대로 확인하면, 대부분의 Flutter iOS 빌드 실패는 30분 안에 범위를 좁히고 해결까지 갈 수 있습니다.

Discuss on Twitter • View on GitHub