Windows에서 Node.js — Native vs WSL2, 어디서 개발해야 하나

Windows에서 Node.js로 개발할 때 가장 먼저 부딪히는 질문 — "WSL2 Linux 안에서 깔까, Windows 네이티브에 깔까?". 둘 다 동작하지만 성능·도구 호환·디버깅 경험이 크게 다르다. 이 가이드는 두 환경의 차이와 결정 기준, 각각 셋업 방법을 정리한다.

대상: Windows 11에서 JavaScript/TypeScript로 개발하는 개발자. Windows 초기 셋업 완료 가정.

TL;DR

결정 1번: 어차피 production은 Linux. WSL2에서 개발하면 production 환경과 동일. 큰 이유 없으면 WSL2 권장.

사전 조건

• Windows 11 22H2+
• WSL2 + Ubuntu 24.04 (Windows 초기 셋업)
• Windows Terminal (선택 — windows-terminal-setup)

1. Native vs WSL2 — 핵심 차이

성능

WSL2의 ext4 파일시스템이 Windows의 NTFS보다 Node의 작은 파일 다수 읽기에 압도적. 단, Windows 파일시스템(/mnt/c/...)을 WSL2에서 mount해 쓰면 더 느림.

도구 호환

디버깅

2. 결정 표

WSL2를 골라야 하는 경우

• production이 Linux — Vercel·AWS·GCP·Heroku 등 99%
• node-gyp 의존 모듈 자주 사용 — sharp·canvas·@tensorflow/tfjs-node
• 빠른 dev 서버 + HMR — 가장 큰 일상 차이
• CI가 Ubuntu/Alpine — Linux에서 검증 → CI 통과 보장
• Mac 동료와 협업 — 거의 동일 환경 (POSIX)

Native Windows를 골라야 하는 경우

• Electron 데스크톱 앱 빌드 — Windows 실행파일 만들기
• Tauri Windows 빌드 — Rust + WebView2
• Windows-only API — Windows COM, Registry 접근
• 단순 자동화 스크립트 — Notepad 자동화 등
• VS Code Remote-WSL이 너무 느린 머신 — 저사양

둘 다 설치

가능. 자주 발생: 회사 dev는 WSL2, 사이드 데스크톱 앱은 Native. 충돌 거의 없음 (PATH 분리).

3. WSL2 Node.js 셋업 (권장)

3.1 WSL Ubuntu 진입

wsl -d Ubuntu-24.04

3.2 mise로 Node 설치 (권장)

# mise 설치 — 언어 버전 관리
curl https://mise.run | sh
echo 'eval "$(/home/$USER/.local/bin/mise activate bash)"' >> ~/.bashrc
exec bash
 
# Node 설치
mise use --global node@22
node --version    # v22.x

mise 자세히: mac/dev-toolchain — Linux도 동일하게 동작.

3.3 또는 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec bash
nvm install --lts
nvm use --lts

3.4 또는 apt (시스템 패키지)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

⚠️ apt 방식은 버전 전환 어렵고 sudo 의존. mise 또는 nvm 권장.

3.5 pnpm·yarn

npm install -g pnpm yarn

3.6 검증

node --version    # v22.x
npm --version
pnpm --version
which node        # ~/.local/share/mise/installs/node/22/bin/node (mise 사용 시)

4. WSL2 + VS Code 통합

4.1 Remote-WSL 확장

VS Code Extensions:

• WSL (ms-vscode-remote.remote-wsl)

설치 후 명령 팔레트 → WSL: Connect to WSL → Ubuntu 선택.

또는 WSL Ubuntu에서:

cd ~/projects/myapp
code .

VS Code가 Windows에서 뜨지만 백엔드는 WSL2.

4.2 효과

• Node·npm·pnpm 명령이 WSL2 안에서 실행
• 파일 시스템은 WSL2의 ext4 (~/projects/myapp)
• 터미널은 WSL2 bash
• 디버거·확장이 WSL2 측에서 동작

Windows 파일시스템(C:\) 안에서 작업하면 안 됨 — 성능 폭락.

5. Native Windows Node.js 셋업

5.1 winget 설치

# 최신 LTS
winget install OpenJS.NodeJS.LTS
 
node --version    # v22.x

5.2 또는 fnm (버전 관리)

winget install Schniz.fnm
 
# PowerShell profile에 자동 활성화
notepad $PROFILE
# 추가:
# fnm env --use-on-cd | Out-String | Invoke-Expression

.nvmrc / package.json#engines.node 발견 시 자동 전환.

5.3 또는 NVM for Windows

winget install CoreyButler.NVMforWindows
 
nvm install lts
nvm use lts

nvm-windows는 unix nvm과 별개 프로젝트. 명령은 비슷.

5.4 build tools (native 모듈 빌드용)

sharp·canvas·bcrypt 등을 빌드하려면:

winget install Microsoft.VisualStudio.2022.BuildTools

또는:

npm install -g windows-build-tools  # 구버전 — Visual Studio Build Tools 권장

5.5 검증

node --version
npm --version
pnpm --version

6. 자주 만나는 함정

6.1 양쪽에 깔린 채 헷갈림

WSL2에 node 설치 + Native Windows에 node 설치 → 터미널마다 다른 버전. 해결:

• WSL bash 안에선 WSL Node (which node → ~/.local/share/mise/...)
• PowerShell에선 Native Node (Get-Command node → C:\Program Files\nodejs\...)
• VS Code 터미널 기본을 명시 (terminal.integrated.defaultProfile.windows: Ubuntu (WSL))

6.2 Windows 파일시스템 mount의 느림

WSL2에서 /mnt/c/Users/me/projects/myapp로 작업 → I/O 5-10배 느림.

# ❌ 느림
cd /mnt/c/Users/me/projects/myapp
npm install
 
# ✅ 빠름
cp -r /mnt/c/Users/me/projects/myapp ~/projects/
cd ~/projects/myapp
npm install

기존 Windows 폴더의 프로젝트를 WSL2로 옮길 때 한 번만 이전.

6.3 줄바꿈 (CRLF vs LF)

WSL2에서 작업 후 Git commit → Windows에서 같은 파일 열면 CRLF 변환됨. 해결:

git config --global core.autocrlf input    # WSL2 안에서

자세히: /multi-os/git-line-endings.

6.4 npm install -g 시 EACCES

# WSL2 안에서 — npm prefix 변경
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc
exec bash

Native Windows에선 PowerShell 관리자 권한.

7. 검증 (선택한 환경에서)

# WSL2 또는 PowerShell
node --version
npm --version
 
# package.json 생성 + 의존성 설치 + 실행
mkdir hello-node && cd hello-node
npm init -y
npm install express
cat > index.js <<'EOF'
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('hello'));
app.listen(3000, () => console.log('http://localhost:3000'));
EOF
node index.js
# → 브라우저 localhost:3000 → "hello"

성공하면 셋업 완료.

8. 트러블슈팅

Cannot find module 'sharp' (또는 다른 native 모듈)

• Native Windows: Visual Studio Build Tools 설치 후 npm rebuild
• WSL2: sudo apt install build-essential 후 npm rebuild

WSL2에서 dev 서버 접근 안 됨 (Windows 브라우저)

• WSL2가 0.0.0.0 또는 ::에 바인딩 (예: next dev -H 0.0.0.0)
• Windows 11 22H2+ 는 자동 포워딩, 이전 버전은 localhost로 접근 가능

pnpm 명령이 안 보임 (PATH 문제)

• npm install -g 한 위치를 확인 → PATH에 추가
• Native: npm config get prefix → <prefix>\bin
• WSL2: $HOME/.npm-global/bin 또는 mise 경로

node-gyp 빌드 시 "Python not found"

• Native Windows: winget install Python.Python.3.12
• WSL2: sudo apt install python3 python3-pip

Electron 빌드는 가능한가 (WSL2에서)

가능하지만 복잡함. Electron의 packaging은 host OS의 산출물(.exe/.app/.deb) 생성하므로 Windows native에서 Windows 빌드, WSL2에서 Linux 빌드. Electron은 Native Windows 권장.

Next.js dev 서버가 자주 재시작 (WSL2)

/mnt/c/ 안에서 작업하지 마라 (§6.2). 또한 next.config.ts에 webpackDevMiddleware 옵션 또는 turbopack 사용.

9. 다음 단계

• Docker on WSL2 — /windows/docker-wsl2
• WSL 튜닝 (메모리·CPU·네트워크) — /windows/wsl-tuning
• Windows 초기 셋업 — /windows/initial-setup
• Mac에서 같은 셋업 — /mac/dev-toolchain (mise 동일 사용 가능)

참고

• Node.js 공식
• mise 공식
• fnm GitHub
• VS Code WSL 문서

변경 이력

• 2026-05-16: 첫 작성. WSL vs Native 비교 + 셋업 양쪽 + 함정 4종 + 트러블슈팅 6종.