macOS에서 ServBay로 프로젝트별 Node.js 버전 독립 설정 가이드

ServBay는 개발자를 위해 설계된 강력한 로컬 웹 개발 환경으로, Node.js를 비롯한 다양한 프로그래밍 언어, 데이터베이스, 웹 서버를 통합한 올인원 솔루션입니다. ServBay의 가장 큰 장점 중 하나는 여러 버전의 Node.js를 기본적으로 지원하고, 유연하게 관리할 수 있다는 점입니다. 간단한 설정 파일만으로 각 프로젝트마다 필요한 Node.js 버전을 지정할 수 있어, NVM, fnm 등의 외부 버전 관리 도구나 Docker 컨테이너 없이도 손쉽게 개발 환경을 관리하고, 전역 환경 오염이나 버전 충돌을 근본적으로 방지할 수 있습니다.

이 문서에서는 ServBay의 .servbay.config 파일을 활용해 프로젝트 단위로 Node.js 버전을 제어하는 방법을 자세하게 안내합니다.

왜 ServBay의 .servbay.config로 Node.js 버전 관리를 해야 할까요?

기존의 Node.js 버전 관리 방식, 즉 NVM 사용이나 수동 설치의 경우, 여러 가지 불편함이 존재합니다.

• 전역 환경 오염 및 충돌: 전역 설치나 버전 관리 도구의 전역 전환은 프로젝트 간 의존성 충돌을 야기하기 쉽습니다.
• 설치 및 컴파일 시간 소모: 새 버전 설치 또는 아키텍처(예: x86_64와 arm64) 전환 시 모듈을 재컴파일해야 하는 경우가 많아 복잡하고 시간이 오래 걸립니다.
• Docker 환경의 무거움: 단지 특정 Node.js 버전만 맞추고 싶은 상황에서 Docker 컨테이너는 부담이 지나칩니다.

ServBay는 주요 Node.js 버전(현재 v12 ~ v23의 모든 주/부 버전 지원)을 미리 설치(ServBay 앱의 “소프트웨어 패키지” 영역에서 관리 가능)하고, .servbay.config 파일과 연동해 보다 우아한 대안을 제공합니다.

• 즉시 전환: 다양한 버전이 사전 설치되어 있어 전환이 거의 즉시 이루어집니다.
• 프로젝트 분리: 설정은 개별 프로젝트 폴더 내에서만 적용되어 진정한 프로젝트별 버전 독립이 가능합니다.
• 전역 환경 오염 없음: 시스템 전체 환경에는 영향이 없어 macOS를 깔끔하게 유지할 수 있습니다.
• ServBay 연동: ServBay의 다른 패키지(PHP, DB, 웹서버 등)와도 매끄럽게 협업이 가능합니다.

사전 준비

시작 전 다음을 확인하세요.

1. MacOS에 ServBay를 정상적으로 설치 후 실행했습니다.
2. ServBay 앱의 “소프트웨어 패키지(Packages)” 목록에서 프로젝트에 필요한 Node.js 버전이 설치 및 활성화되어 있습니다.
3. 특정 Node.js 버전을 적용하고자 하는 프로젝트 디렉토리가 준비되어 있습니다.

핵심 원리

ServBay는 통합된 터미널 환경에서 현재 작업하려는 디렉토리를 감시합니다. cd 명령 등으로 특정 폴더에 진입하면 ServBay는 현재 폴더에서 상위 디렉토리까지 .servbay.config 파일이 존재하는지 찾습니다(가장 가까운 파일이 우선 적용). .servbay.config를 발견하면, 파일 안의 설정을 읽어 환경 변수(예: PATH)를 자동 조정하여 지정 버전의 Node.js 실행 경로를 사용합니다.

이 방식으로 각 프로젝트 폴더 별로 자동으로 적합한 Node.js 버전을 적용할 수 있어, 번거로운 수동 전환이 필요 없습니다.

설정 방법

프로젝트별 Node.js 버전 지정은 단 2단계만 거치면 됩니다.

1단계: .servbay.config 파일 생성 및 편집

프로젝트 루트(대개 package.json이 존재하는 폴더)에 .servbay.config라는 새 파일을 만드세요.

좋아하는 텍스트 에디터로 파일을 열고 다음을 추가합니다.

# 프로젝트에 사용할 Node.js 주 버전 지정
# ServBay는 해당 주버전에서 설치된 최신 버전을 자동 선택
NODE_VERSION=20

# (선택) npm 또는 pnpm 미러 레지스트리 설정 — 의존성 설치 속도 향상용
# 중국 내라면 로컬 미러 추천
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# (선택) npm 또는 pnpm 캐시 폴더 경로
# ServBay 임시 디렉토리로 지정하면 시스템 오염이나 사용자 폴더 공간 낭비 방지
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

설정 항목 설명:

• NODE_VERSION: 필수. 프로젝트에서 필요한 Node.js 주 버전 지정. 예를 들어 20으로 지정하면, ServBay에 설치된 Node.js 20.x 최신 버전을 자동 사용합니다. 반드시 ServBay에 해당 버전이 활성화되어야 합니다.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: 선택 사항. Yarn 또는 npm의 패키지 레지스트리 주소를 설정합니다. 특히 네트워크 환경이 좋지 않을 때 설치 속도를 크게 높일 수 있습니다.
• NPM_CONFIG_CACHE: 선택 사항. npm 또는 pnpm의 캐시 폴더 지정. ServBay 임시 폴더(/Applications/ServBay/tmp/npm/cache)로 모아 관리하면 캐시 파일이 시스템 곳곳에 남지 않아 효율적입니다.

수정 후 .servbay.config 파일을 저장하고 닫으세요.

2단계: ServBay 터미널에서 버전 적용 확인

1. ServBay 앱 메인 화면을 엽니다.

2. "터미널(Terminal)" 버튼을 눌러 ServBay 내장 터미널을 실행합니다.

3. 터미널에서 cd 명령으로 프로젝트 폴더로 이동합니다.

   cd /Applications/ServBay/www/your-project-name

   (위 경로에서 /Applications/ServBay/www/your-project-name을 실제 프로젝트 경로로 대체하세요)

4. node -v 명령으로 활성화된 Node.js 버전을 확인합니다.

   node -v

   설정한 .servbay.config의 Node.js 버전(예: v20.x.x)이 출력되어야 합니다.

5. 추가로 npm -v, pnpm -v, yarn -v 등 명령을 실행해 패키지 매니저가 올바른 Node.js와 연결되는지도 체크할 수 있습니다.

이제 해당 프로젝트 폴더 내에서 실행하는 Node.js 및 npm/pnpm/yarn 명령은 모두 .servbay.config에 지정한 Node.js 버전 및 관련 환경으로 동작합니다.

실전 예시

서로 다른 Node.js 버전이 필요한 두 프로젝트(예: project-a는 Node.js v18, project-b는 Node.js v20)를 예로 들어, .servbay.config를 활용한 버전 자동 전환 과정을 살펴봅니다.

1. 프로젝트 폴더 및 설정 파일 생성

   # ServBay의 www 폴더에 샘플 프로젝트 폴더 만들기
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # project-a에 Node.js v18 버전 지정
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # project-b에 Node.js v20 버전 지정
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. ServBay 터미널에서 버전별 전환 테스트

   ServBay 터미널을 열고 다음 순서로 입력하세요.

   # project-a 폴더 이동
   cd /Applications/ServBay/www/project-a
   # Node.js 버전 확인
   node -v
   # 예시 출력: v18.x.x
   
   # project-b로 이동
   cd ../project-b
   # Node.js 버전 확인
   node -v
   # 예시 출력: v20.x.x
   
   # 다시 project-a로 이동
   cd ../project-a
   # Node.js 버전 확인
   node -v
   # 예시 출력: v18.x.x

위 예시에서처럼 ServBay는 현재 위치한 디렉토리의 .servbay.config의 NODE_VERSION 값을 자동 반영하여 Node.js 버전을 변경합니다. 별도의 전환 명령 없이 프로젝트별 Node.js 환경이 유지됩니다.

아래 이미지는 각기 다른 프로젝트 폴더 간 이동 시 .servbay.config에 맞추어 Node.js 버전이 자동으로 바뀌는 모습을 시각적으로 보여줍니다(예시 이미지, 실제 화면과 다를 수 있음):

주의사항

• .servbay.config 파일은 반드시 프로젝트 폴더나 그 상위 폴더에 위치해야 합니다. ServBay는 상위로 올라가며 가장 먼저 찾은 .servbay.config를 적용합니다(최단 거리 원칙).
• ServBay 내장 터미널에서 작업하거나, ServBay 환경 변수가 올바르게 적용된 외부 터미널이어야 설정이 힘을 발휘합니다.
• NODE_VERSION 값은 ServBay 앱에 설치 및 활성화된 버전이어야 합니다. 미설치 버전을 지정하면 기본값이 적용되거나 Node.js 명령을 인식하지 못할 수 있습니다.
• .servbay.config 파일 설정은 해당 터미널 세션 및 하위 프로세스에만 한정(시스템 전체에는 영향 없음), ServBay 환경 밖에서는 적용되지 않습니다.

자주 묻는 질문 (FAQ)

Q: 프로젝트 폴더에 .servbay.config 파일이 없으면 어떻게 되나요?

A: ServBay는 현재 폴더와 상위 폴더 어디에도 .servbay.config가 없으면 전역 설정 또는 ServBay의 기본 Node.js 버전(“기본값”으로 지정된 버전 등)을 사용합니다.

Q: ServBay는 어떤 Node.js 버전들을 지원하나요?

A: ServBay 앱을 열고 왼쪽 메뉴의 “소프트웨어 패키지(Packages)” 섹션으로 이동하세요. 설치 및 사용 가능한 Node.js 버전 목록을 볼 수 있고, 체크박스로 활성/비활성도 손쉽게 조정할 수 있습니다.

Q: .servbay.config의 설정이 시스템 전체에 영향을 주나요?

A: 전혀 그렇지 않습니다. .servbay.config의 내용은 ServBay 터미널 세션(또는 ServBay 환경 변수 기반의 프로세스)에만 한정적으로 적용됩니다. 시스템 전체 환경 설정에는 영향을 주지 않으니, 프로젝트 독립성을 안전하게 보장합니다.

Q: NODE_VERSION 외에 다른 ServBay 관련 설정도 .servbay.config에서 할 수 있나요?

A: 네, .servbay.config는 ServBay에서 제공하는 프로젝트별 환경 변수 설정 메커니즘입니다. Node.js 외에도 환경 변수로 지정 가능한 사항이 점차 확대되고 있으며, 프로젝트 폴더 하위에서 실행하는 모든 명령어에 이런 변수가 적용됩니다. ServBay 버전에 따라 지원 항목은 달라질 수 있지만, 환경 변수 설정이 핵심 기능입니다.

마무리

ServBay의 .servbay.config 파일을 활용하면 각 로컬 프로젝트별로 Node.js 버전을 손쉽고 효율적으로 독립 관리할 수 있습니다. 기존의 버전 관리 툴이나 컨테이너 방식보다 훨씬 가볍고, ServBay 통합 개발 환경에 완벽하게 녹아듭니다. 프로젝트 협업과 개발 안정성 모두를 높여주는 최적의 방식, 지금 바로 프로젝트에 .servbay.config를 적용해 ServBay의 강력한 개발 경험을 만끽해 보세요!