node-gyp는 개발자가 여러 플랫폼에서 네이티브 Node 애드온 모듈을 컴파일할 수 있게 해주는 유용한 도구입니다. 현재 매우 널리 사용되고 있어 대부분의 NPM 패키지에 의존성으로 포함되어 있는 경우가 많습니다.
대부분의 운영체제에서 node-gyp는 특별한 문제를 일으키지 않습니다. node-gyp와 나머지 NPM 패키지의 설치는 보통 원활하고 효율적으로 진행됩니다. 하지만 모든 사용자에게 그런 것은 아닙니다. 일부 개발자들은 macOS에서 node-gyp를 재구축(rebuild)하는 데 어려움을 겪었다고 보고했으며, 이로 인해 개발 경험이 크게 저하되었습니다. 이 오류는 수많은 함정을 만들어내고 문제가 발생할 여지를 다양하게 남깁니다.
이 문제는 새로운 것이 아닙니다. 구버전 macOS를 사용하던 개발자들이 이미 이 오류를 경험한 바 있습니다. macOS Catalina가 출시된 이후에는 새 macOS 버전으로 업그레이드한 후 Mac에서 node-gyp 재구축이 실패한다는 보고도 여러 건 접수되었습니다. 이 오류로 인해 개발자들은 필요한 node-gyp 패키지를 설치하지 못하는 상황에 처했습니다.
이 오류를 겪어본 개발자라면 Mac에서 node-gyp 재구축이 실패하는 것이 얼마나 답답한 일인지 잘 알 것입니다. 이 오류를 해결하기 전까지는 앱이나 소프트웨어 개발을 진행할 수 없기 때문입니다. 다행히 아래에 소개하는 해결 방법들을 활용하면 이 오류 때문에 프로젝트를 진행하지 못하는 상황을 벗어날 수 있습니다.
Node-Gyp란 무엇인가?
node-gyp는 C 또는 C++로 작성된 네이티브 Node.js 모듈인 Node.js 애드온을 컴파일하는 데 사용되는 도구입니다. 이러한 모듈은 node-gyp 같은 도구를 사용해 사용자의 머신에서 컴파일해야 합니다. node-gyp는 Windows, macOS, Linux에서 모두 작동합니다.
node-gyp는 일관된 인터페이스 덕분에 일반적으로 사용하기 쉽습니다. 서로 다른 플랫폼에서 동일한 명령어로 모듈을 빌드하거나 재구축할 수도 있습니다. 또한 node-gyp는 여러 대상 버전의 Node를 지원합니다.
Mojave 또는 그 이전 버전의 macOS에서 npm gyp 오류가 발생한다면, node-gyp가 작동하기 위한 요구 사항을 먼저 꼼꼼히 확인해야 합니다.
macOS에서 node-gyp가 작동하기 위해 설치해야 하는 요구 사항은 다음과 같습니다:
- Python v2.7, v3.5, v3.6 또는 v3.7
- Xcode – macOS, iOS, iPadOS용 앱을 개발할 수 있게 해주는 유틸리티
또한 Xcode의 소프트웨어 개발 도구 및 라이브러리 모음의 일부인 올바른 버전의 Xcode Command Line Tools를 설치해야 합니다.
Xcode Command Line Tools를 설치하려면 아래 지침을 따르세요:
- Mac에서 Xcode를 실행합니다.
- Xcode 메뉴에서 환경설정(Preferences)을 선택합니다.
- 일반(General) 패널에서 다운로드(Downloads)를 클릭합니다.
- 다운로드 창이 열리면 구성 요소(Components) 탭을 클릭합니다.
- Command Line Tools 옆의 설치(Install) 버튼을 클릭합니다.
- Apple Developer 계정으로 로그인하여 설치 과정을 완료합니다.
macOS Catalina를 사용 중이라면, 해당 Catalina 버전에 맞는 Command Line Tools for Xcode를 Apple 개발자 사이트에서 다운로드할 수 있습니다. 예를 들어 macOS 10.15.3의 경우 파일명은 Command_Line_Tools_for_Xcode_11.3.1.dmg여야 합니다. 올바른 구성 요소를 설치했다면 node-gyp를 성공적으로 빌드할 수 있을 것입니다. 만약 Mac에서 node-gyp 재구축 실패 오류가 발생한다면, 무엇이 잘못되었는지 확인하기 위해 이러한 구성 요소들을 점검해야 합니다.
Node-Gyp 재구축 오류 해결 방법
노드 모듈 설치는 간단한 과정입니다. 특정 명령어만 실행하면 바로 사용할 수 있습니다. 하지만 Mac에서 node-gyp 재구축 실패 오류가 발생했다면, 한 걸음 물러나 무엇이 문제였는지 파악해야 합니다.
그 전에 먼저 시도해볼 기본적인 문제 해결 단계는 다음과 같습니다:
- 시스템에 영향을 줄 수 있는 임시 버그를 제거하기 위해 컴퓨터를 재시작합니다.
- 불필요한 앱을 모두 종료하여 시스템 리소스를 확보합니다.
- 백신 프로그램이나 안티 멀웨어 프로그램 등 보안 소프트웨어를 일시적으로 비활성화합니다.
- Mac 복구 앱을 사용하여 시스템을 정리합니다.
그래도 node-gyp 재구축 오류가 발생한다면, 아래의 해결 방법들을 살펴보고 자신에게 맞는 방법을 찾아보세요.
해결 방법 #1: 필수 구성 요소 재확인
Mojave 또는 다른 macOS 버전에서 npm gyp 오류가 발생했을 때 가장 먼저 해야 할 일은 node-gyp의 설치 요구 사항을 다시 확인하는 것입니다. 위에서 언급했듯이 작동하려면 세 가지 구성 요소가 필요합니다:
- Python
- Xcode
- Xcode Command Line Tools
모듈을 컴파일하는 데 필요한 C와 C++ 언어 설치도 잊지 마세요. 이 중 하나라도 누락되었거나 제대로 작동하지 않으면 반드시 재구축 실패 오류가 발생합니다. 누락되었거나 문제가 있는 구성 요소를 다시 설치하면 문제를 해결하는 데 도움이 될 것입니다.
해결 방법 #2: Node-Gyp 구성 요소 업데이트
때로는 이러한 구성 요소를 설치하는 것만으로는 부족합니다. 자신의 macOS에 맞는 올바른 버전을 사용하고 있는지 확인해야 합니다. Python은 자신에게 맞는 버전에 따라 v2.7, v3.5, v3.6 또는 v3.7 중에서 선택할 수 있습니다. Xcode는 Apple 공식 사이트에서 다운로드할 수 있습니다. 만약을 대비해 최신 버전의 node-gyp도 함께 설치하는 것이 좋습니다.
해결 방법 #3: Acid Test(무결성 테스트) 수행
컴퓨터에 설치된 Xcode Command Line Tools가 제대로 설치되어 node-gyp와 함께 작동할 수 있는지 확인하려면, 다음 단계에 따라 acid test를 실행해볼 수 있습니다:
- Xcode에서 다음 명령어를 실행합니다:
/usr/sbin/pkgutil –packages | grep CL - 목록에 com.apple.pkg.CLTools_Executables가 표시되면 문제가 없는 것입니다. 표시되지 않는다면 이 테스트는 실패한 것이므로 다시 설치해야 합니다.
- 다음 명령어를 실행합니다:
/usr/sbin/pkgutil –pkg-info com.apple.pkg.CLTools_Executables - 목록에 version: 11.0.0(또는 그 이상)이 표시되어야 합니다. 그렇지 않다면 이 테스트 역시 실패한 것이므로 재설치가 필요합니다.
해결 방법 #4: 다른 Python 버전으로 전환
많은 개발자들이 활성 환경에서 사용하는 Python 버전을 변경하는 것이 문제 해결에 도움이 되었다고 밝혔습니다. 이는 macOS 버전, Node 버전, 그리고 사용 중인 Python 버전 간의 호환성과 관련이 있습니다. 일부 사용자들은 v2.7 같은 구버전 Python이 신버전보다 더 안정적이라는 것을 발견했습니다. 여러 버전을 실험해보며 자신에게 가장 적합한 버전을 찾아보세요.
마무리
Mac에서 node-gyp 재구축 실패 오류가 발생하면 번거로울 뿐만 아니라, 원인을 파악하는 데만 많은 시간을 낭비하게 됩니다. 따라서 이 오류를 만난다면 위의 가이드를 참고하여 정확히 어떻게 해결해야 하는지 확인하세요. 필수 구성 요소 점검부터 버전 업데이트, 무결성 테스트, Python 버전 변경까지 단계별로 시도하면 대부분의 경우 문제를 해결할 수 있습니다.