02752025년 8월 14일

[Flutter] Flutter iOS 빌드 오류: Pods_Runner not found 해결하기

상황

Flutter 프로젝트를 iOS 시뮬레이터에서 실행하려고 했는데, 빌드 중에 아래와 같은 오류가 발생했다.

code

Error (Xcode): Framework 'Pods_Runner' not found
Error (Xcode): Linker command failed with exit code 1 (use -v to see invocation)

처음에는 빌드 로그 상단에 잔뜩 출력된 WFParameter... 관련 메시지가 보여서 그게 원인인 줄 알았지만,
실제 빌드 실패의 핵심 원인은 CocoaPods 의존성 문제였다.

1) WFParameter 관련 메시지란?

빌드 로그 초반에 보이는

code

Failed to index parameter type: <WFInputTypeParameter ...>

같은 메시지는 iOS 단축어(Shortcuts)·워크플로우 시스템에서 사용하는 내부 매개변수 타입 변환 실패 로그이다.

WF는 Workflow의 약자 → iOS 단축어 앱의 내부 프레임워크
iOS 15 이후, 단축어(Shortcuts) 기능이 시스템 전반에 통합되면서앱 빌드 과정에서 시뮬레이터/환경이 해당 API를 스캔할 때 이런 경고성 로그가 뜰 수 있음
중요: 이 메시지는 Flutter 앱 빌드 실패와 직접적인 연관이 없다.단지 빌드 과정에서 iOS 프레임워크 메타데이터를 인덱싱하다 발생한 경고일 뿐이었다.

2) CocoaPods이란?

: CocoaPods는 iOS·macOS 앱에서 외부 라이브러리(패키지)를 관리하는 의존성 관리 도구이다.

Flutter iOS 프로젝트도 ios/Podfile을 통해 CocoaPods로 네이티브 라이브러리를 관리
예: Firebase, Google Sign-In, 이미지 처리 라이브러리 등
pod install 명령어를 통해 해당 의존성을 설치하고,Xcode가 이를 빌드에 포함시킬 수 있도록 설정

3) CocoaPods 의존성 문제란?

설치된 Pod 버전이 깨졌거나 누락된 경우
Podfile.lock과 실제 설치된 Pod 버전이 불일치한 경우
iOS SDK 업데이트 후 기존 Pods 캐시와 호환되지 않는 경우이런 상황이면 빌드 시 필요한 네이티브 라이브러리를 찾지 못해 오류가 발생합니다.

4) Pods_Runner.framework를 찾지 못한다는 의미

Pods_Runner.framework는 CocoaPods이 Flutter iOS 프로젝트에 설정한 Runner 앱 전용 프레임워크 묶음이다.

Flutter iOS 프로젝트의 Runner 타겟은 Pod로 관리되는 여러 라이브러리를 한데 묶어 Pods_Runner.framework 형태로 링크한다.
빌드 과정은 크게 3단계
1. 컴파일(Compile) – 소스 코드를 목적 코드로 변환
2. 링크(Link) – 목적 코드와 필요한 라이브러리를 묶어 실행 파일 생성
3. 패키징(Package) – 최종 앱 번들(.app) 생성
여기서 링크 단계에서 Pods_Runner.framework가 없으면,필요한 라이브러리를 참조할 수 없어서 빌드가 중단된다.

해결 방법

1) CocoaPods 초기화 및 재설치

code

cd ios
pod deintegrate       # 기존 Pod 완전 제거
pod install           # 의존성 재설치
cd ..
flutter clean         # Flutter 빌드 캐시 삭제
flutter pub get       # pubspec.yaml 패키지 재설치
flutter run

2) Pod 버전 업데이트 (필요 시)

code

sudo gem install cocoapods
pod repo update

결과

위 과정을 거치니 더 이상 Pods_Runner not found 오류 없이 정상적으로 시뮬레이터에서 앱이 실행되었다.

결국 원인은 Pods 재설치로 해결 가능했던 CocoaPods 의존성 문제였다.

정리- WFParameter 경고: iOS 단축어 API 인덱싱 중 발생하는 로그, 빌드 실패 원인 아님- CocoaPods: iOS 라이브러리 의존성 관리 도구, Flutter iOS 빌드에도 필수- Pods_Runner.framework 오류: 링크 단계에서 Pod 프레임워크 누락 시 발생, pod install로 해결 가능

최근 글