Node.js 문제 해결 가이드

이 문서는 ServBay 로컬 개발 환경을 사용하는 개발자들이 Node.js 패키지 사용 중 흔히 겪는 문제들을 해결할 수 있도록 돕기 위한 안내서입니다.

Node.js/npm/pnpm/yarn 명령어 버전을 찾을 수 없거나 인식이 안됨

ServBay에서 Node.js, npm, pnpm 또는 yarn 명령을 실행할 때 아래와 같은 오류 메시지가 나오는 경우, 시스템이 지정한 Node.js 버전의 실행 파일을 찾지 못한다는 뜻입니다:

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

이는 주로 ServBay에 해당 Node.js 버전이 설치되어 있지 않거나, 또는 nvm, homebrew 등 다른 도구로 설치한 Node.js 버전을 사용하려 했으나 환경설정 문제로 ServBay에서 해당 실행 파일을 인식하지 못할 때 발생합니다.

안내

ServBay를 설치하면 시스템에 ServBay 전용 스크립트 별칭(Script Alias)이 설정되어, Node.js는 ServBay 내부에 설치된 패키지를 우선적으로 사용합니다. 만약 지정 버전을 ServBay에서 찾지 못할 경우, 순차적으로 nvm의 기본 버전, 그 다음 homebrew로 설치된 버전을 찾아 시도합니다. 이 모든 경로에서 찾지 못하면 위와 같은 오류가 표시됩니다.

원인 분석:

1. ServBay 앱 내에 요청한 Node.js 버전이 설치되어 있지 않습니다.
2. 시스템에 nvm 또는 homebrew가 설치되어 있으며, 이들로 관리되는 Node.js 버전을 사용하려 하지만, shell 환경설정(특히 PATH 또는 NVM_BIN 환경 변수)이 올바르지 않아 ServBay의 우선순위 탐색 기능이 외부 Node.js를 찾지 못합니다.

해결 방법:

nvm으로 Node.js를 설치했음에도 위의 오류가 발생한다면, shell 환경설정에서 NVM_BIN 환경 변수 누락이나 오설정이 흔한 원인입니다. nvm이 정상적으로 설치되었다면, 해당 변수는 자동으로 설정되고 nvm 경로의 Node.js 실행파일 위치를 가리키며, 이는 nvm이 정상작동하는데 필수적입니다.

따라서, 사용 중인 shell 환경설정 파일(예: ~/.zshrc, ~/.bash_profile 등)에서 nvm 관련 설정을 점검하여, NVM_BIN 변수가 올바르게 설정되고 export되어 있는지 확인하세요. 설정 변경 후에는 설정파일을 다시 불러오거나(source ~/.zshrc 명령 실행, 혹은 터미널 재시작) 하면 됩니다. 이렇게 하면, ServBay가 nvm으로 관리하는 Node.js 버전을 정상적으로 인식할 수 있습니다.

nvm이나 homebrew 사용이 없거나, ServBay에서 설치한 Node.js 버전을 사용하고자 한다면, 해당 버전이 ServBay 앱의 ‘패키지’ 탭에서 설치되어 있는지 반드시 확인하세요.

node-sass 등 일부 npm 패키지 사용 시 아키텍처 미지원 오류

Apple Silicon(M1/M2/M3/M4 등 Arm64 아키텍처) 기반의 macOS를 사용하실 경우, node-sass와 같이 구형이거나 네이티브 모듈에 의존하는 npm 패키지 사용 시 Unsupported architecture (arm64)와 유사한 오류가 발생할 수 있습니다. 해당 패키지들이 x86_64 아키텍처만 지원하거나, Arm64 지원이 누락된 경우 주로 이런 문제가 나타납니다.

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

원인 분석:

일부 npm 패키지는 C++ 등 네이티브 코드의 컴파일이 필요하며, 이는 각각의 CPU 아키텍처에 맞게 빌드되어야 합니다. 구 버전 패키지들은 Arm64용 바이너리나 빌드 구성을 포함하지 않는 경우가 많아, Apple Silicon 환경에서 호환성 오류가 발생합니다.

해결 방법:

1. 현대적이고 Arm64를 지원하는 대체 패키지로 교체(권장)

   가장 권장되는 방법은 Arm64 환경을 완벽하게 지원하며, 유지 관리가 활발한 현대 패키지로 교체하는 것입니다. 예를 들어, 더 이상 적극적으로 유지보수되지 않는 node-sass 대신, 공식적으로 Arm64를 지원하며 최신 프론트엔드 생태계에서 널리 채택된 sass 패키지를 사용하는 것이 좋습니다.

   npm uninstall node-sass
   npm install --save-dev sass

2. ServBay에서 x86_64 아키텍처 Node.js 설치 후 Rosetta 2로 실행(권장하지 않음)

   ServBay는 Node.js 패키지의 x86_64 아키텍처 버전 설치를 지원합니다. Apple Silicon Mac에서 해당 방식을 사용하면 macOS의 Rosetta 2 변환 계층을 통해 Node.js 및 의존 x86_64 네이티브 모듈을 실행할 수 있습니다. ServBay 앱의 ‘패키지’ 탭에서 x86_64 버전을 선택해 설치할 수 있습니다.

   

   주의: 이 방법은 장기적인 해결책으로 권장되지 않습니다. Rosetta 2 에뮬레이션에 의존하기 때문에 성능 저하가 발생할 수 있고, 네이티브 Arm64 환경보다 호환성이 떨어질 수 있습니다. 1번 권장 방식을 우선 고려하시기 바랍니다.

---