Flutter iOS 빌드 No such module Flutter 해결법

서론

Flutter로 iOS 빌드를 하다 보면 Xcode에서 갑자기 No such module 'Flutter' 에러를 만나는 경우가 있습니다. 보통은 CocoaPods 통합이 깨졌거나, Flutter가 생성해야 하는 iOS 빌드 설정 파일(Generated.xcconfig 등)이 누락되었거나, 워크스페이스/타깃 설정이 꼬여서 Flutter.framework를 찾지 못하는 상태입니다.

이 글은 “일단 pod install 해보세요” 수준이 아니라, 왜 이런 문제가 생기는지(빌드 그래프 관점)와 어떤 순서로 점검하면 가장 빠르게 복구되는지에 초점을 맞춥니다.

에러가 의미하는 것: Swift 모듈 로딩 실패

Xcode에서 import Flutter를 하는 Swift(또는 ObjC 브리징) 코드가 있을 때, 컴파일러가 Flutter 모듈을 찾지 못하면 아래 형태로 터집니다.

No such module 'Flutter'

여기서 말하는 Flutter는 Dart/Flutter SDK 자체가 아니라, iOS 빌드 시 CocoaPods가 연결해주는 Flutter 엔진/프레임워크(Flutter.framework) 및 관련 Pod 설정을 의미합니다.

즉, 근본 원인은 다음 중 하나로 수렴합니다.

• Pods/ 및 .xcworkspace가 깨졌거나 열지 않음
• Podfile/pod install 결과가 현재 Flutter 프로젝트 상태와 불일치
• ios/Flutter/Generated.xcconfig 등 Flutter가 생성하는 설정 파일이 없음
• Xcode 빌드 설정(검색 경로, 스키마, 구성)이 잘못되어 Flutter.framework가 링크/임포트 경로에 없음

가장 흔한 원인 Top 6

1) .xcworkspace가 아니라 .xcodeproj를 열었다

CocoaPods를 쓰는 iOS 프로젝트는 반드시 Runner.xcworkspace를 열어야 합니다. .xcodeproj로 열면 Pods 통합이 빠져 Flutter 모듈을 못 찾는 상황이 자주 발생합니다.

• 올바른 파일: ios/Runner.xcworkspace

2) pod install이 안 되었거나 Pods 캐시가 꼬였다

Flutter iOS는 Pod 설치 결과에 의존합니다. 특히 Xcode 업그레이드, Flutter 채널 변경, 브랜치 전환(의존성 변경) 후에 Pods가 꼬이는 일이 잦습니다.

3) Generated.xcconfig 누락

ios/Flutter/Generated.xcconfig는 flutter pub get 또는 flutter build ios 과정에서 생성됩니다. 이 파일이 없으면 Pod가 참조해야 하는 Flutter 관련 설정이 비어버려 모듈 탐색이 실패할 수 있습니다.

4) iOS 폴더를 수동 편집(특히 Podfile/xcconfig)하다가 include가 끊김

ios/Runner/ 아래의 .xcconfig에서 Pods-Runner.*.xcconfig를 include하는 라인이 삭제되거나, 반대로 Flutter 쪽 include가 빠지면 빌드 설정이 분리됩니다.

5) 아카이브(Release)에서만 터지는 구성 문제

Debug에서는 되는데 Archive/Release에서만 No such module Flutter가 나면, 보통 빌드 구성별 설정(Release xcconfig, Framework Search Paths, Other Linker Flags) 중 하나가 Debug와 다르게 되어 있습니다.

6) M1/M2 + Ruby/CocoaPods 환경 문제로 Pod 설치가 불완전

Pod 설치 자체가 경고 없이 끝난 것처럼 보여도 실제로는 스크립트 단계에서 실패하거나, 아키텍처 이슈로 일부 아티팩트가 누락되는 경우가 있습니다.

빠른 복구 루틴(대부분 여기서 끝납니다)

아래는 “가장 재현성이 높은” 초기화 절차입니다. 의존성/캐시 문제를 한 번에 정리합니다.

1) Flutter 및 iOS 빌드 산출물 정리

flutter clean
rm -rf ios/Pods ios/.symlinks ios/Flutter/Flutter.framework ios/Flutter/Flutter.podspec
rm -rf ios/Runner.xcworkspace

2) pub 의존성 재생성(Generated.xcconfig 생성 유도)

flutter pub get

ios/Flutter/Generated.xcconfig가 생성되었는지 확인하세요.

ls -al ios/Flutter/Generated.xcconfig

3) Pods 재설치

cd ios
pod repo update
pod install
cd ..

4) 반드시 워크스페이스로 열기

open ios/Runner.xcworkspace

여기까지로도 80~90%는 해결됩니다.

그래도 안 되면: 원인별 정밀 점검 체크리스트

A) Podfile이 Flutter 템플릿 형태인지 확인

기본 Flutter iOS 템플릿은 대략 아래 흐름을 갖습니다(프로젝트별로 약간 다를 수 있음).

platform :ios, '12.0'

# ...

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
  end
end

핵심은 flutter_install_all_ios_pods와 flutter_additional_ios_build_settings가 살아있어야 한다는 점입니다. 이 둘이 빠지면 Flutter Pod 통합이 불완전해질 수 있습니다.

> 참고: use_frameworks!는 플러그인 구성에 따라 필요/불필요가 갈립니다. 하지만 이미 프로젝트가 이 설정에 의존하고 있었다면 임의로 제거하면 더 큰 링크 문제로 번질 수 있습니다.

B) ios/Flutter/Debug.xcconfig / Release.xcconfig include 확인

ios/Flutter/Debug.xcconfig 또는 ios/Flutter/Release.xcconfig가 아래처럼 Pods 설정을 include하고 있는지 확인합니다.

#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
#include "Generated.xcconfig"

Release도 유사합니다.

#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
#include "Generated.xcconfig"

• Generated.xcconfig가 누락되면 Flutter 관련 빌드 변수가 비어버립니다.
• Pods include가 누락되면 Flutter 모듈을 제공하는 설정(검색 경로/링커 플래그)이 Runner 타깃에 전달되지 않습니다.

C) Xcode에서 “Runner” 타깃의 Build Settings 확인

특히 Release에서만 터질 때 아래 항목을 봅니다.

• Framework Search Paths: $(inherited)가 포함되어 있는지
• Other Linker Flags: $(inherited)가 포함되어 있는지
• Swift Compiler - Search Paths: $(inherited)가 포함되어 있는지

$(inherited)가 빠지면 Pods가 주입하는 설정을 Runner가 상속하지 못해 No such module류가 발생하기 쉽습니다.

D) 스키마/구성 혼동(특히 CI)

CI에서만 실패한다면, 로컬과 다른 구성을 빌드하고 있을 가능성이 큽니다.

• 로컬: Debug on Simulator
• CI: Release + Archive + Code Signing

CI에서 다음처럼 명시적으로 워크스페이스를 지정해야 합니다.

xcodebuild \
  -workspace ios/Runner.xcworkspace \
  -scheme Runner \
  -configuration Release \
  -sdk iphoneos \
  -archivePath build/Runner.xcarchive \
  archive

-project ios/Runner.xcodeproj로 빌드하면 Pods가 빠져 동일 증상이 날 수 있습니다.

E) Swift Package / 모듈 캐시 꼬임

Xcode의 DerivedData가 깨져 모듈 인덱스가 꼬이는 경우도 있습니다. 이때는 DerivedData를 정리합니다.

rm -rf ~/Library/Developer/Xcode/DerivedData

그 후 Xcode를 재실행하고 빌드하세요.

F) 플러그인이 iOS 최소 버전/모듈 설정을 깨는 경우

특정 플러그인이 iOS deployment target을 올리거나, use_frameworks! 강제 등으로 Pod 구성이 바뀌면서 Flutter 모듈 로딩이 연쇄적으로 실패하는 경우가 있습니다.

이때는 다음 순서가 안전합니다.

1. 최근 추가/업데이트한 플러그인을 pubspec.yaml에서 되돌림
2. flutter clean + pod install 재수행
3. 문제 플러그인의 iOS 설치 가이드(추가 Pod 설정 요구 등) 재확인

“아카이브에서만” 발생하는 케이스의 실전 해결 패턴

Release에서만 No such module Flutter가 뜨는 경우는 대개 Release.xcconfig의 include 누락 또는 빌드 설정 상속(inherited) 누락입니다.

다음 2가지를 우선 확인하세요.

1. ios/Flutter/Release.xcconfig에 Generated.xcconfig 포함

#include "Generated.xcconfig"

2. Runner 타깃의 Build Settings에 $(inherited) 존재

• Framework Search Paths
• Other Linker Flags

이 두 가지가 맞으면, Pods가 제공하는 Flutter 관련 설정이 Release에도 전달됩니다.

재발 방지: 브랜치 전환/업그레이드 시 습관

• 브랜치 전환 후 iOS 쪽 에러가 나면, Pods를 의심하고 ios/Pods를 과감히 지우고 재설치
• Xcode 업데이트 후에는 DerivedData 정리 + pod repo update
• CI는 반드시 Runner.xcworkspace로 빌드하고, pod install이 선행되도록 구성

이런 접근은 “원인을 한 번에 제거하는 초기화”와 “구성별(Release/Debug) 설정 상속 점검”을 분리해 문제를 빠르게 좁힙니다. 디버깅을 할 때도 체크리스트가 있으면 불필요한 삽질이 줄어듭니다.

비슷한 결의 트러블슈팅 글

빌드/배포 파이프라인에서 발생하는 문제는 대개 ‘상태가 꼬였다’가 핵심이며, 원인을 구조적으로 좁히는 방식이 통합니다. 아래 글들도 같은 관점의 실전 디버깅 사례입니다.

• Terraform apply 멈춤 - AzureRM 120초 타임아웃
• OpenAI 429와 Rate Limit 헤더로 재시도 설계

마무리

No such module Flutter는 “Flutter가 없다”가 아니라, Xcode가 Flutter 모듈을 찾을 수 있는 경로/설정을 전달받지 못했다는 신호입니다. 따라서 해결은 대부분 다음 두 갈래로 정리됩니다.

• Pods/워크스페이스 통합 복구(초기화 + pod 재설치)
• Release/Debug 구성별 xcconfig 및 inherited 설정 점검

위의 빠른 복구 루틴으로 먼저 정상 상태를 만들고, 재발 시에는 Generated.xcconfig와 .xcworkspace, 그리고 $(inherited)를 최우선으로 확인해 보세요.