React Native는 지속적으로 발전하며 새로운 버전을 출시합니다. 하지만 업그레이드 과정에서 종종 예상치 못한 빌드 오류에 직면할 수 있습니다. 특히 React Native 0.75.1 버전으로 업그레이드할 때 'com.facebook.react.settings' 플러그인을 찾을 수 없다는 오류는 흔하게 발생하는 문제입니다. 이 글에서는 이 오류의 원인을 명확히 짚고, 단계별로 해결하는 방법을 상세히 안내합니다.
1. 문제 상황 파악하기
React Native 0.75.1 버전으로 업그레이드한 후 안드로이드 빌드(npx react-native run-android)를 시도하면, 다음과 같은 오류 메시지가 발생하며 빌드가 실패합니다. 이는 Gradle이 특정 플러그인을 찾지 못해 발생하는 문제입니다.
Error Plugin [id: 'com.facebook.react.settings'] was not found in any of the following sources:
* Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
* Included Builds (No included builds contain this plugin)
* Plugin Repositories (plugin dependency must include a version number for this source)
2. 오류의 주요 원인 분석
이 오류는 React Native 0.75.x 버전에서 안드로이드 빌드 시스템인 **Gradle의 설정 방식이 변경되었기 때문**에 발생합니다. 이전 버전에서 사용하던 방식이 새로운 버전과 호환되지 않아 Gradle이 필요한 플러그인을 로드하지 못하는 것입니다. 구체적인 원인은 다음과 같습니다.
settings.gradle파일의 설정 변경: React Native 0.75.x부터는settings.gradle파일에서@react-native/gradle-plugin을 직접includeBuild로 지정하는 새로운 방식이 도입되었습니다. 이전 버전의 설정이 그대로 남아있으면 오류가 발생합니다.- 의존성 누락:
@react-native/gradle-plugin패키지가 제대로 설치되지 않았거나,package.json에 포함되지 않았을 수 있습니다. - 캐시 문제: Gradle 캐시가 오래되었거나 꼬여서 이전 버전의 설정 정보를 계속 참조할 수 있습니다.
3. 단계별 해결 방법
3.1. settings.gradle 파일 수정 (핵심 해결책)
가장 중요한 해결책입니다. android/settings.gradle 파일을 열고, 아래 코드와 같이 **새로운 설정 방식**으로 변경해야 합니다. 이는 @react-native/gradle-plugin을 빌드에 포함시키고, 네이티브 모듈을 올바르게 연결하는 역할을 합니다.
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
// React Native의 Gradle 플러그인을 빌드에 포함
includeBuild('../node_modules/@react-native/gradle-plugin')
// 네이티브 모듈 자동 연결 설정
apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle");
applyNativeModulesSettingsGradle(settings)
include ':app'
3.2. @react-native/gradle-plugin 의존성 확인 및 설치
프로젝트의 package.json 파일에 @react-native/gradle-plugin 의존성이 포함되어 있는지 확인하세요. 만약 없다면, 다음 명령어를 사용하여 설치해야 합니다.
npm install --save-dev @react-native/gradle-plugin
3.3. Gradle 버전 업데이트
새로운 React Native 버전은 최신 Gradle 버전과 호환되도록 설계되었습니다. android/gradle/wrapper/gradle-wrapper.properties 파일의 distributionUrl을 확인하고, 필요한 경우 최신 버전으로 업데이트하세요. 일반적으로 gradle-7.5.1 이상을 권장합니다.
distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-all.zip
3.4. 프로젝트 클린 및 재빌드
위의 수정사항을 적용한 후, 캐시 문제를 해결하기 위해 **프로젝트를 완전히 클린하고 재빌드**하는 것이 중요합니다.
cd android
./gradlew clean
cd ..
npx react-native run-android
중요: npm run android 대신 npx react-native run-android를 사용하면 최신 CLI가 적용되어 빌드 프로세스가 더 안정적으로 작동할 수 있습니다.
4. 문제가 해결되지 않을 때 시도할 수 있는 추가 팁
node_modules삭제 및 재설치:rm -rf node_modules yarn.lock package-lock.json && npm install명령을 실행하여 의존성을 완전히 재설치해보세요.- 공식 업그레이드 가이드 참조: React Native 공식 웹사이트의 Upgrade Helper를 사용하여 0.74.x에서 0.75.x로 변경된 모든 파일 내용을 확인하세요.
- Android Studio 캐시 초기화: Android Studio에서 'File' > 'Invalidate Caches / Restart'를 실행하여 IDE 캐시를 정리하세요.
결론
React Native 0.75.1 업그레이드 시 발생하는 'com.facebook.react.settings' 플러그인 오류는 Gradle 설정 변경사항을 제대로 반영하지 못해 발생하는 문제입니다. 이 가이드에서 제시한 settings.gradle 파일 수정, 의존성 확인, 그리고 프로젝트 클린/재빌드 단계를 순서대로 따르면 대부분의 경우 문제가 해결될 것입니다. 업그레이드 시에는 항상 공식 문서를 참고하고, 변경된 설정 사항을 꼼꼼히 확인하는 습관을 들이는 것이 중요합니다. Happy coding!