프로그래밍/flutter로 앱만들기

Flutter iOS 앱 개발할 때 알아야 할 `pubspec.yaml`과 `CocoaPods`의 관계

kugancity 2025. 5. 15. 16:32
반응형

 

 

 

Flutter로 앱을 개발하다 보면 pubspec.yaml만 잘 관리하면 다 되는 것처럼 느껴지지만,
iOS 앱을 빌드하려는 순간부터 갑자기 pod install, Podfile, Firebase iOS SDK 같은 생소한 용어들이 등장하기 시작합니다.

특히 Firebase 같은 네이티브 기능이 포함된 패키지를 사용할 때는 이런 구조를 제대로 이해하고 있지 않으면,
빌드 오류에 막히고 무엇이 문제인지 알 수 없게 되는 경우가 많습니다.

이 글에서는 Flutter iOS 앱 개발에서 Flutter 패키지 (pubspec.yaml)와 CocoaPods (Podfile)가 어떻게 연결되어 있는지,
그리고 왜 서로 영향을 주고받는지 이론적으로 명확하게 정리해보려고 합니다.

 

 

 

1️⃣ pubspec.yaml은 무엇을 정의하는가?

pubspec.yaml은 Flutter 프로젝트에서 사용하는 Dart 패키지를 정의하는 설정 파일입니다.

예시:

dependencies:
  firebase_auth: ^4.0.0
  firebase_crashlytics: ^3.4.9

이렇게 하면 Dart 코드에서 firebase_auth, firebase_crashlytics API를 사용할 수 있습니다.
하지만 중요한 건 이 Flutter 패키지들이 내부적으로 iOS에서 실제로 동작하려면, 네이티브 코드가 필요하다는 점입니다.

 

 

2️⃣ Flutter 패키지는 .podspec을 통해 iOS 네이티브 라이브러리와 연결된다

Flutter에서 사용하는 패키지 중 일부는 iOS에서 Swift 또는 Objective-C로 구현된 기능을 호출해야 하는 경우가 있습니다.
예: firebase_auth는 Dart 코드만으로는 작동하지 않으며, 실제로는 FirebaseAuth.framework를 불러옵니다.

이때 사용하는 것이 .podspec 파일입니다.

  • firebase_auth 패키지 내부에 ios/firebase_auth.podspec 존재
  • CocoaPods에게 "이 Flutter 패키지는 iOS SDK의 어떤 네이티브 코드에 의존한다"고 알려줌

3️⃣ .symlinks/plugins/ 폴더의 역할

flutter pub get을 실행하면
.pub-cache에 있는 패키지들이 ios/.symlinks/plugins/ 폴더에 심볼릭 링크로 연결됩니다.

이 경로는 CocoaPods가 .podspec 파일을 탐지하는 데 사용됩니다.

4️⃣ pod install은 실제 iOS 네이티브 라이브러리를 설치한다

flutter pub get은 Dart 의존성을 설치하지만,
pod install은 Podfile을 기반으로 iOS 네이티브 SDK(Firebase 등)를 설치합니다.

예: firebase_crashlytics → Firebase/Crashlytics 설치됨

이걸 실행하지 않으면 iOS 빌드 중 헤더를 못 찾거나 라이브러리가 누락되어 오류 발생

5️⃣ iOS 빌드 흐름 요약

[ pubspec.yaml ]
  ↓ flutter pub get
[ .pub-cache 내 Dart 패키지 ] (내부에 .podspec 존재)
  ↓ .symlinks/plugins 로 연결
[ pod install ]
  ↓ .podspec 기준으로 iOS SDK 설치 (Firebase 등)
[ ios/Pods ] 실제 iOS 라이브러리 저장소

즉, Flutter 패키지 하나를 추가하면, 그 패키지가 필요로 하는 iOS SDK가 .podspec을 통해 CocoaPods에 의해 설치됩니다.

6️⃣ Android와는 뭐가 다를까?

플랫폼 네이티브 연동 방식
Android build.gradle, .aar
iOS Podfile, .podspec, CocoaPods

Android는 .aar만 포함되면 빌드 가능하지만,
iOS는 CocoaPods를 통해 네이티브 프레임워크를 직접 설치해야 합니다.

7️⃣ 왜 Flutter iOS에서 pod 오류가 자주 발생하는가?

  • .podspec이 가리키는 SDK 버전이 현재 Xcode 또는 다른 Pod들과 호환되지 않음
  • use_frameworks!, modular_headers! 설정이 충돌 발생
  • Firebase SDK처럼 내부적으로 C++까지 포함된 경우, 빌드 규칙이 매우 민감함

즉, Flutter 코드가 문제가 아니고,
내부에서 사용하는 iOS 네이티브 라이브러리와 컴파일러의 충돌이 원인일 때가 많습니다.

✅ 정리

구성요소 역할
pubspec.yaml Flutter에서 사용하는 Dart 패키지를 정의
.podspec 해당 Dart 패키지가 iOS에서 어떤 SDK를 요구하는지 명시
pod install .podspec 기준으로 실제 iOS SDK 설치
.symlinks/plugins CocoaPods가 .podspec을 읽을 수 있도록 연결해주는 브리지
ios/Pods 최종적으로 설치된 iOS 네이티브 라이브러리

 

 

Flutter로 iOS 앱을 개발하면서 iOS 빌드가 터지는 원인이 Flutter 자체가 아닌 CocoaPods이나 .podspec 때문이라는 걸 모르고
며칠을 고생한 적이 한두 번이 아니었습니다.

이 구조를 이해하고 나면, 왜 pod install이 필요한지, 왜 firebase_crashlytics가 버전에 따라 빌드 오류를 내는지 모두 명확해집니다.

 

 

 

지금 이 글을 읽고 계신다면, CocoaPods와 Flutter 패키지 사이의 관계를
"아! 이렇게 되는 거구나!" 하고 잡으셨기를 바랍니다.

 

 

 

 

 

 

728x90
반응형
저작자표시 (새창열림)