Node.js 설치 안됨·오류 해결 — node 명령어 인식 안됨
'node' is not recognized as an internal or external command, operable program or batch file. / zsh: command not found: node
이런 증상일 때
Node.js 를 설치했는데도 터미널에서 node -v 를 치면 Windows 는 "is not recognized", 맥/리눅스는 "command not found: node" 가 뜹니다. 설치 직후 기존 터미널 창에서, 또는 nvm 으로 설치한 뒤 새 터미널을 열었을 때 자주 나타납니다. npm·npx 도 같이 인식되지 않는 경우가 많습니다.
원인
- Node.js 는 설치됐지만 node.exe 가 있는 폴더(C:\Program Files\nodejs)가 PATH 환경변수에 등록되지 않음 (Windows)
- PATH 를 바꾼 뒤 기존 터미널을 닫지 않아 변경이 반영되지 않음 — 새 창에서만 적용됨
- nvm 으로 설치했는데 ~/.zshrc(또는 ~/.bashrc) 에 nvm 초기화 줄이 없어 새 셸에서 node 가 안 잡힘 (macOS/Linux)
- Windows 에서 nvm-sh(맥·리눅스용 스크립트)를 잘못 설치 — Windows 는 coreybutler 의 nvm-windows 를 써야 함
- 윈도우 사용자명이 한글이라 C:\Users\홍길동\AppData\Roaming\npm 처럼 한글이 섞인 npm 전역 경로가 PATH 인식·일부 패키지에서 깨짐 (한국 환경)
해결 방법
nodejs.org 에서 Windows LTS 인스톨러(.msi)를 받아 설치할 때 "Add to PATH" 옵션을 켭니다. 설치가 끝나면 열려 있던 CMD·PowerShell·VS Code 를 모두 닫고 새로 열어야 PATH 가 반영됩니다.
node -v
npm -v이미 설치돼 있는데 인식 안 되면 "시스템 환경 변수 편집 → 환경 변수 → Path → 편집 → 새로 만들기" 로 node 경로를 추가합니다. 기본 설치 경로는 C:\Program Files\nodejs 이고, 전역 npm 은 C:\Users\사용자명\AppData\Roaming\npm 입니다. 등록 후 PATH 가 잡혔는지 확인합니다.
# PowerShell 에서 node 가 PATH 에 있는지 확인
Get-Command node
# 또는 CMD 에서
where nodenvm 로 설치한 경우 ~/.zshrc(zsh) 또는 ~/.bashrc 에 초기화 줄이 있어야 새 터미널에서 node 가 잡힙니다. 줄이 없으면 추가하고 셸을 다시 불러옵니다. 저는 12개 사이트를 nvm 으로 Node 버전 분리해 쓰는데, 이 세 줄이 빠지면 매번 command not found 가 납니다.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
# 추가 후 적용
source ~/.zshrcnvm 자체가 없으면 공식 설치 스크립트로 깔고, LTS 를 설치한 뒤 기본 버전으로 지정합니다. 프로젝트별 Node 버전을 깔끔하게 분리할 수 있어 버전 충돌이 거의 사라집니다.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
nvm install --lts
nvm alias default lts/*
node -vWindows 에서는 맥·리눅스용 nvm-sh 가 동작하지 않습니다. coreybutler 의 nvm-windows 를 winget 으로 설치하고, 관리자 권한 셸에서 LTS 를 설치합니다. 설치 후 새 관리자 터미널을 열어야 반영됩니다.
winget install -e --id CoreyButler.NVMforWindows
# 새 관리자 PowerShell 에서
nvm install lts
nvm use lts
node -v윈도우 사용자명이 한글이면 C:\Users\홍길동\... 경로의 한글 때문에 전역 npm 패키지 PATH·일부 빌드 도구가 깨지는 사고가 납니다. npm 전역 경로를 한글이 없는 폴더로 옮겨 회피합니다. 가비아·카페24 등 국내 호스팅 Windows 환경에서도 동일하게 적용됩니다.
# 한글 없는 경로로 전역 prefix 이동
mkdir C:\nodejs-global
npm config set prefix C:\nodejs-global
# C:\nodejs-global 을 PATH 에 추가 후 새 터미널에서 확인
npm -g list