[React-native] Error : Command PhaseScriptExecution failed ... (순환 참조를 곁들인)

HongDuHyeon·2025년 1월 20일

react native

실전에서 맞고 온 에러 디버깅..? 귀하다 귀해...

났다 빌드 중 에러가...

개쩌는 React-native 개발자들이라면 한번 쯤은 겪어볼만 한 에러인

Command PhaseScriptExecution failed with a nonzero exit code

가 나오고 xcode 빌드가 터져버렸다.
젠장

내가 그래도 우리 팀 xcode 빌드 에러 탐지반인데 이 문제는 너무 많은 경우에 생기는 것 같다.

💡 에러가 나오는 이유

이 에러는 Xcode의 빌드 단계 중 "Run Script Phase" 에서 문제가 발생했음을 나타낸다.
그 말인 무엇이냐? React-Native 프로젝트에서 이 에러는는 보통 JavaScript 번들 생성 및 복사할 때 나올 수 있는 에러라는 것이다.

🚀 팀에서 겪은 에러 케이스

PhaseScriptExecution 단계는 Metro Bundler를 호출하여 JavaScript 번들을 생성하는데 분명 develop branch에선 에러 없이 빌드가 잘 되는데 feature의 특정 브랜치에서만 안되는 걸 확인했다.

어라... 그럴리가 없는데... 하면서 커밋을 하나하나 checkout 해가면서 어떤 곳이 문제인지 파악했다. 먼저 확인한 결과 순환참조가 있는 부분을 발견했다.

🚀 깨알 꿀팁

순환 참조란 ?
주로 모듈, 컴포넌트, 또는 유틸리티 함수들이 서로를 참조하거나 의존하는 상황에서 나타납니다.

🚀 해결 및 대처 방법

순환 참조를 발견 후 터널시야에 갇혀 코드를 짠 흔적을 확인했다. 내가 겪은 케이스는
enum값을 여러군데에서 참조하면서 심지어 setState까지 핸들링하는 케이스였다.
화면을 보여주는 스크린에서 여러군데에 참조를 하고 그게 꼬리를 물고 이어지다보니 순환참조가 발생해서 각각 알맞는 기능을 하는 파일에서 다시 export 해줘서 해결했다.

추가로 알게 된 명령어가 있는데

🚀 순환 참조를 알아내는 법

냅다 코드 던지고 설명하기

yarn react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/

팀에서 이 코드를 통해 찾는 법을 배웠다. 하지만 왜 이 코드를 사용해야하는가? 에 대한 건 크게 되묻지 않아서 직접 찾아봤다. (현재 시각 퇴근 후 3시간 지난 내 방 책상 앞)

yarn react-native bundle
- 프로젝트의 js코드를 하나의 파일로 번들링하고 앱에서 필요한 모든 종속성(assets까지 포함)을 포함한다. (아래 예시 사진)
--platform android
- 번들링할 플랫폼을 지정합니다. 여기서는 Android용 번들을 생성한다.
- 왜 안드로이드냐? 라고 할 수 있지만 iOS 빌드는 Xcode 내부에서 Metro를 호출하므로 에러가 간접적으로 나타나는 반면, Android 명령어는 직접 번들링 과정만 실행하므로 더 명확한 에러 메시지를 제공한다. (ChatGPT 참고했음)
--dev false
- 더 정확하게 확인하기 위해 개발용 빌드가 아닌 릴리즈 빌드를 사용하기 위해 dev mode false 처리
--entry-file index.js
- 번들링의 진입점(Entry Point)을 지정한다.
- 대부분 index.js가 디폴트입니다.
--bundle-output android/app/src/main/assets/index.android.bundle
- 번들에 포함된 에셋들을 저장할 위치를 지정한다.