NestJS CLI 인식 문제 해결하기: PATH 설정 가이드

목차

1. 문제 상황
2. 원인 분석
3. 해결 방법
4. 운영체제별 추가 설정
5. 문제 해결 검증
6. 자주 발생하는 다른 문제들

문제 상황

NestJS CLI를 전역으로 설치했음에도 불구하고 터미널에서 nest 명령어를 인식하지 못하는 문제가 발생합니다.

$ npm install -g @nestjs/cli
$ nest new my-project
zsh: command not found: nest

원인 분석

이 문제는 주로 npm의 전역 설치 경로가 시스템의 PATH 환경변수에 제대로 등록되지 않아서 발생합니다. npm이 패키지를 전역으로 설치하는 위치를 시스템이 인식하지 못하는 것입니다.

npm 전역 설치 경로 확인

먼저 npm이 패키지를 전역으로 설치하는 위치를 확인해야 합니다:

$ npm config get prefix
/usr/local  # 또는 다른 경로가 출력될 수 있습니다

해결 방법

1. 현재 PATH 설정 확인

현재 설정된 PATH 환경변수를 확인합니다:

$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin  # 예시 출력

2. PATH 환경변수 설정

사용 중인 셸(Shell)의 설정 파일을 수정합니다. zsh를 사용하는 경우 ~/.zshrc, bash를 사용하는 경우 ~/.bashrc 파일을 수정합니다.

# ~/.zshrc 또는 ~/.bashrc 파일에 추가
export PATH="/usr/local/bin:$PATH"  # 기본 전역 설치 경로 사용 시
# 또는
export PATH="$HOME/.npm-global/bin:$PATH"  # 사용자 정의 전역 설치 경로 사용 시

3. 설정 적용

변경된 설정을 현재 셸 세션에 적용합니다:

$ source ~/.zshrc  # zsh 사용 시
# 또는
$ source ~/.bashrc  # bash 사용 시

운영체제별 추가 설정

macOS

macOS의 경우 권한 문제가 발생할 수 있습니다. 이 경우 다음과 같이 해결합니다:

# /usr/local/bin 디렉토리의 권한 확인
$ ls -la /usr/local/bin

# 필요한 경우 권한 수정
$ sudo chown -R $USER /usr/local/bin

Linux

Linux 시스템에서는 사용자별 npm 전역 설치 디렉토리를 설정하는 것이 권장됩니다:

# 사용자별 전역 설치 디렉토리 설정
$ mkdir ~/.npm-global
$ npm config set prefix '~/.npm-global'
$ export PATH=~/.npm-global/bin:$PATH

Windows

Windows에서는 환경 변수를 시스템 설정에서 직접 추가할 수 있습니다:

1. 시스템 속성 > 고급 > 환경 변수
2. 사용자 변수의 Path에 npm 전역 설치 경로 추가
3. 일반적으로 %USERPROFILE%\AppData\Roaming\npm

문제 해결 검증

설정이 완료된 후 다음 명령어로 NestJS CLI가 정상적으로 인식되는지 확인합니다:

# NestJS CLI 버전 확인
$ nest -v
9.0.0  # 예시 출력

# 새 프로젝트 생성 테스트
$ nest new test-project

자주 발생하는 다른 문제들

1. 권한 문제

Error: EACCES: permission denied

해결 방법:

$ sudo chown -R $USER ~/.npm
$ sudo chown -R $USER /usr/local/lib/node_modules

2. 캐시 문제

$ npm cache clean --force
$ npm install -g @nestjs/cli

3. Node.js 버전 문제

# Node.js 버전 확인
$ node -v

# nvm을 사용하여 버전 변경
$ nvm use 16  # 또는 다른 LTS 버전

마치며

PATH 설정 문제는 개발 환경을 구축할 때 자주 마주치는 이슈 중 하나입니다. 이 문제를 해결함으로써 NestJS CLI를 정상적으로 사용할 수 있게 되었습니다. 추가로 다음과 같은 사항들을 고려하면 좋습니다:

• npm 권한 관련 설정 검토
• Node.js와 npm 버전 호환성 확인
• 프로젝트별 로컬 설치 vs 전역 설치 전략 수립

참고 자료

• NestJS 공식 문서
• npm 공식 문서의 전역 설치 가이드
• Node.js 설치 및 설정 가이드