Expo 프로젝트에서 네이티브 모듈 추가 시 겪은 시행착오와 해결 과정

 

네이티브 모듈을 추가하는 과정에서의 접근 방법

1. 기본적인 설치 과정

• 패키지 추가
• app.json 환경 설정
• eas build 또는 expo prebuild (네이티브 모듈은 Expo Go에서 동작하지 않음)

첫 번째 문제: 빌드는 성공하지만 앱이 실행되지 않음

eas build --profile development --platform ios

• 빌드는 성공하지만 앱이 실행되지 않음 (JS 번들 로딩 실패로 추측)
• 앱 실행 과정:
  1. 네이티브 코드 실행
  2. JS 번들 다운로드 (Metro 서버 활용)
  3. JS 실행 및 app.js 진입

두 번째 문제: pod install 오류 발생

npx expo prebuild
cd ios
pod install

• pod install 실행 시 애매한 에러 발생
• 로그가 뚜렷하지 않아 문제의 원인을 파악하기 어려움

 

 

문제 해결을 위한 접근 방법: 바이너리 서치 디버깅 + 최소 재현 환경(MRE) 전략

에러 메시지가 명확하지 않고, 여러 문제가 동시다발적으로 발생했기 때문에 문제 해결에 오랜 시간이 걸렸다. 하루 동안 해결되지 않아 새로운 전략을 도입했다.

[바이너리 서치 디버깅]

• 앱이 정상 동작하던 상태에서 한 단계씩 기능을 추가하며, 어느 시점에 문제가 발생하는지 추적
• 크래시 발생 시점을 찾고 원인을 좁혀가는 방식

[최소 재현 환경 (MRE) 구축]

• 최소한의 코드로 동일한 문제가 발생하는 환경을 만들고, 문제를 명확히 정의
• 스택오버플로우 및 깃허브에 질문을 올리면서 영어로 문제를 정리하는 과정에서 문제를 보다 정확히 이해하게 됨

---

 

 

 

단계별 디버깅 진행 과정

1️⃣ 안정적인 커밋을 기준으로 브랜치 생성

git branch  # 현재 브랜치 확인
git log --oneline  # 커밋 로그 확인
git checkout -b [새 브랜치 이름] [커밋 번호]  # 원하는 커밋에서 브랜치 생성

2️⃣ 단계별 기능 추가 후 테스트

0 단계: 안정적인 버전: node16-no-native

1 단계: node18-no-native

2 단계: ads-only (패키지: react-native-google-mobile-ads , expo-build-properties)

3 단계:  splash-screen

 

---

1 단계: node18-no-native

1. expoGo 테스트: node 16/18: npm start : expoGo 문제없음
2. 네이티브 환경 테스팅: node 16/18 에서 npx expo prebuild → pod install 깨짐

 

🛑 pod install 실행 시 expo_modules! 관련 에러

에러 메시지:

[!] Invalid Podfile file: undefined method `present?' for nil:NilClass.
from /Users/hello/Projects/app/ios/Podfile:39
    * # -------------------------------------------
    * # config = use_native_modules!
    * > use_expo_modules! # #
    * -------------------------------------------

원인 분석:

• expo_modules! 관련 설정이 정상적으로 적용되지 않음
• CocoaPods 설치 문제 가능성

해결 방법:

1. CocoaPods이 정상적으로 설치되었는지 확인
2. pod --version # 버전이 나오지 않으면 재설치 필요
3. CocoaPods 제거하고 루비로 재설치 후 다시 실행

brew uninstall cocoapods //brew로 설치한 cocoapods 제거 
brew install rbenv //brew 로 rbenv 설치 
rbenv install -l // 설치 가능한 ruby 리스트 확인 
rbenv install 3.2.7 //원하는 ruby 버전 설치 
rbenv global 3.2.7 // 전역적으로 ruby 버전 바꿈 
rbenv -v //변경된 루비 버전확인 
vi ~/.zshrc // zshrc 파일 열기 
eval "$(rbenv init - zsh)" // 환경변수 구문 추가(i로 insert) 
source ~/.zshrc //변경사항 적용 ruby -v //3.2.7

 

 

 

🛑 Firebase 관련 use_modular_headers! 오류

에러 메시지:

The Swift pod `FirebaseCoreInternal` depends upon `GoogleUtilities`, which does not define modules.
To opt into those targets generating module maps, set `use_modular_headers!` globally in your Podfile.

원인 분석:

• 일부 Firebase 라이브러리가 모듈화되지 않아 Swift와의 연결이 깨짐

해결 방법:

1. Podfile 내용 수정
2. use_frameworks! :linkage => podfile_properties['ios.useFrameworks'].to_sym if podfile_properties['ios.useFrameworks'] 코드를 use_frameworks! :linkage => :static 로 변경
3. pod install 다시 실행
4. cd ios && pod install

---

 

 

2 단계: ads-only

🛑 react-native-google-mobile-ads 설치 후 Codegen 에러 발생

🔍 문제 상황

React Native 프로젝트에 react-native-google-mobile-ads 모듈을 추가한 후, pod install 실행 시 Codegen 관련 에러가 발생했습니다.

[INSTALL_PODS] [Codegen] Processing RNGoogleMobileAdsSpec
[INSTALL_PODS] [Codegen] Searching for podspec in the project dependencies.
[INSTALL_PODS] [Codegen] Supported Apple platforms: ios for RNGoogleMobileAdsSpec
[INSTALL_PODS] [Codegen] Done.
[INSTALL_PODS] UnsupportedModulePropertyParserError: Module NativeGoogleMobileAdsNativeModule: TypeScript interfaces extending TurboModule must only contain 'FunctionTypeAnnotation's. Property 'onAdEvent' refers to a 'TSTypeReference'.

---

해결 방법

대안 1_ react-native 와 expo를 최신 버전으로 업데이트 한다.

: (25년 1월 기준) expo 52, react-native 76.x

대안 2_ react-native-google-mobile-ads 의 버전을 14.7.2로 다운그레이드한다. ✅ 전체 환경 업데이트보다, 상대적으로 위험 부담이 적은 패키지 다운그레이드 선택

1. 기존 패키지를 제거합니다. : npm uninstall react-native-google-mobile-ads
2. 14.7.2 버전으로 재설치이후 다시 pod install을 실행합니다 : 
npm install react-native-google-mobile-ads@14.7.2
cd ios && pod install

---

 

 

 

배운 점 

1️⃣ 경고까지 잡으려다 길을 잃을 수 있다

• 단순한 오류가 아닌 경고(Warnings)까지 해결하려다 보니, 길을 잃고 뱅뱅 돌게 되었다.
• 디버깅할 때는 먼저 "치명적인 오류"에 집중하고, 나중에 부가적인 경고를 해결하는 것이 효율적이다.

2️⃣ MRE(Minimal Reproducible Example) 방식이 문제 해결에 효과적이다

• 최소 재현 환경(MRE)을 만들면서 문제를 더 명확하게 이해하게 되었다.
• 또한, 스택오버플로우나 깃허브에 질문을 올릴 때 MRE를 활용하니 더 좋은 답변을 받을 수 있었다.

 

 

참고

https://velog.io/@st_hwang/React-Native-%ED%8C%8C%EC%9D%B4%EC%96%B4%EB%B2%A0%EC%9D%B4%EC%8A%A4-ios-%EC%97%B0%EB%8F%99-CocoaPod-%EC%98%A4%EB%A5%98-%ED%95%B4%EA%B2%B0

[React-Native] 파이어베이스 ios 연동 CocoaPod 오류 해결

 

 

https://github.com/invertase/react-native-google-mobile-ads/issues/678

[🐛] Eas build failure with UnsupportedModulePropertyParserError (workaround: use react-native 0.76+ / expo 52+) · Issue #678

https://cotist.tistory.com/52

Ruby 버전 업데이트 및 전역 적용하는 방법