VSCode에서 Node.js 포터블 다중 버전 관리하기

반응형

 

VSCode에서 Node.js 포터블 다중 버전 관리하기

 

📚 목차
1. Node.js 포터블 설치란?
2. 여러 Node.js 버전 병행 설치와 관리
3. VS Code에서 프로젝트별 Node.js 버전 자동 적용
4. 포터블 Node.js 다중 버전 자동 전환 템플릭 구조 만들기
✔ 마무리 - 포터블 Node.js로 완성하는 유연한 개발 환경

 

VSCode에서 다중 버전 Node.js 관리하기 삽화 이미지

1. Node.js 포터블 설치란?

🔷 포터블 버전이란?

Node.js를 일반적으로 설치하면, 시스템 경로(PATH)에 등록되어 전역으로 실행됩니다.

하지만 프로젝트마다 Node.js 버전이 다르거나, 여러 버전을 테스트해야 할 경우 설치형 방식은 충돌이나 관리의 번거로움이 생깁니다.

 

이때 유용한 것이 포터블(Portable) 버전입니다.

포터블 버전은 설치가 필요 없고, 단순히 압축을 풀어놓은 폴더 안에서 바로 실행됩니다.

 

🔷 공식 ZIP 바이너리 다운로드

1. 공식 Node.js 다운로드 페이지 접속

2. Standalone Binary(.zip) 항목에서 원하는 버전 선택

Node.js 다운로드 화면

예시:

node-v20.19.5-win-x64.zip
node-v24.11.0-win-x64.zip

 

3. 각각 압축 해제 후 폴더 배치

D:\NodejsDevelope\node-v20.19.5
D:\NodejsDevelope\node-v22.11.0

 

🔷 실행 확인

VS Code나 CMD에서 직접 실행해보세요.

D:\NodejsDevelope\node-v20.19.5>node -v
v20.19.5

D:\NodejsDevelope\node-v20.19.5>npm -v
10.8.2

 

2. 여러 Node.js 버전 병행 설치와 관리

Node.js를 여러 버전으로 운영해야 하는 이유는 다양합니다.

예를 들어, 오래된 프로젝트는 여전히 Node 18에서만 빌드가 되는데, 새로운 프로젝트는 최신 런타임인 Node 22 기능(ESM, Edge API 등)을 활용해야 할 수도 있죠.

이럴 때 가장 안전하고 깔끔한 방법은 각 버전을 완전히 독립된 포터블 환경으로 유지하는 것입니다.

 

🔷 폴더 구조 설계: 버전별로 명확하게 분리하기

아래와 같은 구조를 추천합니다.

D:\NodejsDevelope\
 ├─ node-v20.19.5\
 └─ node-v24.11.0\

이 디렉터리 구조는 매우 직관적입니다.

각 폴더 하나가 완전한 Node.js 실행 환경이며, 서로 간에 라이브러리나 설정이 간섭하지 않습니다.

 

🔷 버전 전환을 위한 간단한 배치 파일 만들기

여러 버전을 동시에 관리할 때 가장 귀찮은 부분은 PATH 환경 변수 변경입니다.

매번 수동으로 바꾸기보다는, 각 버전에 맞는 전용 배치 파일(.bat) 을 하나씩 만들어두면 훨씬 편리합니다.

 

예를 들어, Node.js 20 버전을 활성화하려면 다음과 같은 스크립트를 작성합니다.

▸ set-node20.bat

@echo off
set PATH=D:\NodejsDevelope\node-v20.19.5;%PATH%
cmd

 

이 파일을 더블클릭하면,
D:\NodejsDevelope\node-v20.19.5 경로가 최우선으로 PATH에 등록된 새 CMD 창이 열립니다.
이제 해당 콘솔에서는 자동으로 Node 20 버전이 활성화됩니다.

 

✔️ 확인 예

버전 전환을 위한 간단한 배치 파일 실행 예시

이렇게 하면 시스템 전체 설정을 건드리지 않고도 원하는 버전의 Node.js를 즉시 전환할 수 있습니다.

 

🔷 시스템 PATH를 수정하지 않는 이유

일반적으로 Node.js를 설치하면, 설치 프로그램이 자동으로 시스템 PATH를 수정하여 전역에서 사용 가능하게 합니다.

하지만 이렇게 하면 다른 버전의 Node를 설치하거나 제거할 때 충돌, npm 링크 꼬임, 글로벌 패키지 경로 문제 등이 자주 발생합니다.

포터블 방식은 이런 문제를 원천 차단합니다.

레지스트리, 환경 변수, 전역 npm 설정에 전혀 손대지 않기 때문에 버전 전환이 완벽하게 독립적이며, 복원도 간단합니다.
폴더를 복사하거나 삭제만 해도 손쉽게 관리가 가능하죠.

 

✔️ 실무에서 자주 쓰는 팁

▸ 여러 버전을 동시에 테스트할 때
터미널을 두 개 띄워 각각 다른 배치 파일(set-node18.bat, set-node22.bat)로 실행하면 두 버전을 병렬로 비교 테스트할 수 있습니다.

▸ npm 글로벌 패키지 충돌 방지

포터블 환경에서는 각 버전별 npm 글로벌 설치 경로도 독립적입니다.

npm install -g로 설치한 패키지는 각 Node 폴더(예: node-v20.19.5 )내부에 저장되므로, 다른 버전에 영향을 주지 않습니다.

▸ 백업과 복원 용이

특정 버전 환경을 그대로 압축해두면, 나중에 동일한 환경을 다른 PC에서 그대로 복원할 수 있습니다.
설치형 Node보다 이식성이 훨씬 뛰어납니다.

반응형

 

3. VS Code에서 프로젝트별 Node.js 버전 자동 적용

이제 포터블 Node.js 환경 구성이 끝났다면, 각 프로젝트에서 VS Code가 자동으로 올바른 Node.js 버전을 인식하도록 만들어봅시다.

이 설정을 적용하면, 프로젝트를 열 때마다 VS Code 터미널이 해당 버전에 맞게 자동 전환되어 빌드 에러나 의존성 불일치 문제를 깔끔하게 방지할 수 있습니다.

 

🔷 .vscode/settings.json으로 환경 변수 재정의

VS Code는 각 프로젝트별로 로컬 설정 디렉터리(.vscode)를 지원합니다.
여기에 settings.json 파일을 만들어, 해당 프로젝트에서 사용할 Node.js 버전을 명시할 수 있습니다.

예를 들어, Node.js 20 버전을 사용하는 프로젝트라면 다음과 같이 설정합니다:

▸ .vscode/settings.json

{
  "terminal.integrated.env.windows": {
    "PATH": "D:\\NodejsDevelope\\node-v20.19.5;%PATH%"
  }
}

이 설정은 VS Code 내장 터미널에만 적용됩니다.

즉, Windows 전체 PATH에는 영향을 주지 않으며, 해당 프로젝트의 터미널에서만 Node.js 20 버전이 우선 적용됩니다.

다른 프로젝트가 Node.js 24를 필요로 한다면, 단순히 경로만 바꿔주면 됩니다.

{
  "terminal.integrated.env.windows": {
    "PATH": "D:\\NodejsDevelope\\node-v24.11.0;%PATH%"
  }
}

 

🔷 적용 확인

설정이 제대로 적용되었는지 확인하려면 VS Code 내에서 터미널을 열고 다음을 입력합니다

기존의 nvm이나 volta 같은 버전 관리 도구는 강력하지만, 윈도우 환경에서 PATH 충돌이나 관리자 권한 문제로 스트레스가 생기기도 합니다.

반면 이 방식은 VS Code의 설정 파일만으로 로컬 PATH를 재정의하므로, 시스템 전체 환경을 건드리지 않으면서도 프로젝트 단위 제어가 가능합니다

 

4. 포터블 Node.js 다중 버전 자동 전환 템플릿 구조

지금까지 포터블 Node.js 버전들을 설치하고, VS Code에서 프로젝트별로 PATH를 지정하는 방법을 살펴봤습니다.
이번에는 이 과정을 체계적으로 정리한 템플릿 구조를 만들어 새 프로젝트를 생성할 때마다 손쉽게 재활용할 수 있도록 해보겠습니다.

 

🔷 폴더 구성 예시

다음은 포터블 Node.js 환경에서 여러 프로젝트가 서로 다른 버전을 자동으로 사용하는 구조 예시입니다.

D:\dev\
 ├─ nodejs\
 │   ├─ v18.20.4\
 │   ├─ v20.17.0\
 │   └─ v22.11.0\
 └─ projects\
     ├─ legacy-api\
     │   └─ .vscode\settings.json   → Node 18
     ├─ frontend-vue\
     │   └─ .vscode\settings.json   → Node 20
     └─ nextjs-latest\
         └─ .vscode\settings.json   → Node 22

▸ nodejs/: Node.js 포터블 버전 저장소 (버전별로 독립된 실행 환경)
▸ projects/: 실제 프로젝트 소스 디렉터리
▸ 각 프로젝트 폴더마다 .vscode/settings.json 파일을 둬서 해당 프로젝트에 필요한 Node.js 버전을 지정합니다.

✔ 마무리 - 포터블 Node.js로 완성하는 유연한 개발 환경

공식 Node.js 포터블 버전과 VS Code의 로컬 설정(.vscode/settings.json) 만으로 프로젝트별로 완전히 독립된 Node.js 환경을 구현할 수 있습니다.

이 방식의 핵심은 “설치가 아닌 구조”입니다.

설치형 Node.js처럼 시스템 전역을 건드리지 않고, 버전별 폴더와 설정만으로 모든 프로젝트를 자유롭게 분리·전환할 수 있습니다.

 

= 관련 글 =

Visual Studio Code 설치 방법 (Installer / Zip 포터블 모드)

Windows Terminal 사용법과 SSH 연결, 오류 수정 및 화면 분할까지

VSCode Remote - SSH로 Python 원격 개발하기

VSCode에서 GitHub Copilot 무료로 설정하고 사용하기

 

---

※ 게시된 글 및 이미지 중 일부는 AI 도구의 도움을 받아 생성되거나 다듬어졌습니다.

반응형