React Native에서 ‘Native Module cannot be null’ 오류 해결하기

React Native에서 'Native Module cannot be null' 오류는 네이티브 모듈을 연동할 때 자주 발생하는 문제입니다. 오류의 원인과 해결 방법을 단계별로 살펴보며, Android와 iOS 각각에서 발생할 수 있는 문제와 해결책을 구체적으로 알아보겠습니다.

 

'Native Module cannot be null' 오류란?

React Native로 개발을 진행하다 보면 가끔 'Native Module cannot be null'이라는 오류 메시지를 마주칠 때가 있습니다. 이 오류는 주로 네이티브 모듈을 자바스크립트와 연결하는 과정에서 발생합니다. 예를 들어, 카메라나 위치 정보 등과 같은 네이티브 기능을 활용하기 위해 모듈을 설치했을 때 해당 모듈이 제대로 연결되지 않았을 경우 이 오류가 발생할 수 있습니다.

 

이 오류는 React Native와 네이티브 환경 간의 연결에 문제가 있을 때 나타나며, 모듈 설치, 링크, 빌드 설정 등 여러 가지 원인으로 인해 발생할 수 있습니다. 따라서 오류의 원인을 정확히 파악하고, 단계별로 문제를 해결해 나가는 것이 중요합니다.

 

주요 원인 분석

네이티브 모듈 설치 및 연결 문제

가장 흔한 원인 중 하나는 네이티브 모듈이 제대로 설치되지 않았거나 연결이 잘못된 경우입니다. 예를 들어, 네이티브 모듈을 설치한 후 react-native link 명령어나 autolinking 기능을 이용해 연결해야 하는데, 이 과정에서 누락이 생길 수 있습니다. 특히 React Native 0.60 이상부터는 자동 링크 기능이 도입되었지만, 가끔 특정 모듈에서 자동으로 링크되지 않는 문제가 발생할 수 있습니다.

빌드 과정에서의 문제

또 다른 원인은 빌드 설정의 문제입니다. Android의 build.gradle 파일이나 iOS의 Podfile 설정이 잘못되어 있으면 네이티브 모듈이 제대로 빌드되지 않아 오류가 발생할 수 있습니다. 특히 iOS에서는 CocoaPods 설치가 제대로 이루어지지 않았거나, Pod 업데이트가 누락된 경우에도 이 오류가 나타날 수 있습니다.

 

문제 해결을 위한 단계별 접근 방법

올바른 네이티브 모듈 설치 방법

먼저, 네이티브 모듈을 설치할 때 올바른 명령어를 사용했는지 확인해야 합니다. 대부분의 네이티브 모듈은 다음과 같이 설치합니다.

npm install react-native-some-module

 

설치 후에는 npx pod-install 명령어를 사용해 iOS의 경우 Podfile을 업데이트해야 합니다.

npx pod-install

 

이 단계에서 오류가 발생하면 설치가 제대로 이루어지지 않을 수 있으므로, npm 또는 yarn을 통해 재설치하거나, Podfile을 직접 점검해 주는 것이 좋습니다.

링크 및 자동 연결 확인

React Native 0.60 이상에서는 대부분의 모듈이 자동으로 링크됩니다. 하지만, 간혹 수동 링크가 필요한 경우가 있습니다. 만약 자동 링크가 제대로 이루어지지 않았다면, 수동으로 Android와 iOS의 설정 파일을 수정해 모듈을 등록해야 합니다.

Android에서의 수동 링크

android/settings.gradle 파일과 MainApplication.java 파일을 수정해야 합니다.

// MainApplication.java
import com.somepackage.SomeModulePackage;  // 모듈 임포트

@Override</p>
protected List<ReactPackage> getPackages() {
	return Arrays.<ReactPackage>asList(
		new MainReactPackage(),
		new SomeModulePackage() // 모듈 추가
	);
}

 

iOS에서의 수동 링크

iOS의 경우, Podfile에 수동으로 모듈을 추가해야 할 수 있습니다.

pod 'ReactNativeSomeModule', :path => '../node_modules/react-native-some-module'

 

위와 같이 Android와 iOS 모두에서 모듈을 직접 추가함으로써 수동으로 링크할 수 있습니다.

빌드 설정 점검

Android의 경우 android/app/build.gradle 파일에서 SDK 버전이나 종속성 설정을 확인해야 합니다. 특히 React Native의 최신 버전과 호환되지 않는 설정이 있을 경우 오류가 발생할 수 있습니다.

android {
	compileSdkVersion 31
	...
}

 

iOS에서는 Podfile을 열어 필요한 모듈이 제대로 추가되어 있는지, 그리고 pod install 명령어가 성공적으로 실행되었는지를 확인해야 합니다.

 

플랫폼별 오류 해결 방법

Android에서 발생하는 오류와 해결책

Android에서 'Native Module cannot be null' 오류가 발생하는 주요 원인은 네이티브 모듈이 MainApplication.java에 제대로 등록되지 않았기 때문입니다. 앞서 설명한 대로, MainApplication.java 파일에 네이티브 모듈을 수동으로 추가하고, 필요에 따라 gradle.properties 파일에서 Gradle 설정을 확인하는 것이 좋습니다.

iOS에서 발생하는 오류와 해결책

iOS에서는 주로 CocoaPods와 관련된 문제가 많습니다. Pod 설치가 제대로 이루어지지 않았거나, use_frameworks! 설정이 잘못된 경우가 그 예입니다. 이때는 Podfile을 다시 점검하고, pod repo update 및 pod install 명령어를 실행해 최신 설정으로 업데이트해야 합니다.

 

추가적인 팁

네이티브 코드 디버깅

네이티브 모듈이 제대로 연결되지 않았을 때는 Android Studio나 Xcode에서 직접 네이티브 코드를 디버깅하는 것이 좋습니다. 이를 통해 오류 메시지를 더 구체적으로 파악하고, 필요한 설정을 수정할 수 있습니다.

네트워크 및 캐시 관련 문제 해결

때로는 네트워크 문제나 캐시로 인해 오류가 발생하기도 합니다. 이럴 때는 npm cache clean --force 또는 yarn cache clean 명령어로 캐시를 정리하고 다시 빌드해 보는 것도 좋은 방법입니다.

 

마무리하며

React Native에서 'Native Module cannot be null' 오류는 네이티브 모듈과의 연동 과정에서 자주 발생하는 문제 중 하나입니다. 이 글에서는 오류의 주요 원인과 해결 방안을 자세히 알아봤으며, Android와 iOS 플랫폼에서 각각 어떻게 문제를 해결할 수 있는지 구체적으로 다뤄보았습니다. 이러한 문제를 해결하려면 네이티브 모듈 설치와 빌드 과정을 꼼꼼히 확인하고, 필요할 때 수동으로 설정을 추가하는 것이 중요합니다. 항상 최신 설정과 버전을 유지하며, 디버깅 툴을 활용해 문제를 빠르게 해결하는 습관을 가져보는게 좋겠습니다.