<a href="https://github.com/nvm-sh/logos">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nvm-sh/logos/HEAD/nvm-logo-white.svg" />
<img src="https://raw.githubusercontent.com/nvm-sh/logos/HEAD/nvm-logo-color.svg" height="50" alt="nvm project logo" />
</picture>
</a>
노드 버전 관리자 (Node Version Manager) [Tests][3] [nvm version][4] CII Best Practices
<!-- 이 목차를 업데이트하려면 `npm install`을 실행한 후 `npm run doctoc`을 실행했는지 확인하세요 -->
<!-- START doctoc 생성된 TOC, 자동 업데이트를 위해 주석 유지 -->
<!-- 이 섹션을 편집하지 말고, 대신 doctoc을 다시 실행하여 업데이트하세요 -->
목차 (Table of Contents)
노드 버전 관리자 (Node Version Manager) 사용법
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
소개 (Intro)
nvm을 사용하면 명령줄(command line)을 통해 node의 다양한 버전을 빠르고 쉽게 설치하고 사용할 수 있습니다.
예시:
$ nvm install 24
Now using node v24.14.0 (npm v11.9.0)
$ node -v
...
이처럼 간단합니다!
개요
nvm은 node.js을 위한 버전 관리자(version manager)이며, 사용자별로 설치되고 셸(shell)마다 호출되도록 설계되었습니다. nvm은 POSIX 호환 셸(sh, dash, ksh, zsh, bash) 등 모든 셸에서 작동하며, 특히 unix, macOS, 그리고 Windows WSL 플랫폼에서 사용 가능합니다.
<a id="installation-and-update"></a>
<a id="install-script"></a>
설치 및 업데이트
설치 및 업데이트 스크립트
nvm을 **설치(install)**하거나 **업데이트(update)**하려면 설치 스크립트를 실행해야 합니다. 이를 위해 수동으로 스크립트를 다운로드하여 실행하거나, 다음 cURL 또는 Wget 명령어를 사용할 수 있습니다:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash
위 명령어 중 어느 것을 실행하든 스크립트를 다운로드하고 실행합니다. 이 스크립트는 nvm 저장소를 ~/.nvm으로 클론(clone)한 다음, 아래 코드 조각의 소스 라인들을 올바른 프로필 파일(~/.bashrc, ~/.bash_profile, ~/.zshrc, 또는 ~/.profile)에 추가하려고 시도합니다. 만약 설치 스크립트가 잘못된 프로필 파일을 업데이트하는 것을 발견했다면, $PROFILE 환경 변수(env var)를 해당 프로필 파일의 경로로 설정한 다음, 설치 스크립트를 다시 실행하십시오.
<a id="profile_snippet"></a>
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
추가 참고 사항
-
환경 변수 $XDG_CONFIG_HOME이 존재하면, nvm 파일들이 그곳에 배치됩니다.
-
위의 스크립트 끝에 --no-use를 추가하여 사용자가 수동으로 사용(use)하기 전까지 nvm 사용을 연기할 수 있습니다:
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" --no-use # 이 명령어는 기본 버전을 자동 사용하지 않고 nvm을 로드합니다.
환경 변수 NVM_SOURCE, NVM_DIR, PROFILE, 및 NODE_VERSION을 사용하여 설치 소스, 디렉토리, 프로필, 버전을 사용자 정의할 수 있습니다. 예시: curl ... | NVM_DIR="path/to/nvm". 이때 NVM_DIR에 후행 슬래시가 포함되지 않도록 하십시오.
설치 프로그램은 사용 가능한 방식으로 nvm을 다운로드하기 위해 git, curl, 또는 wget을 사용할 수 있습니다.
이미 zsh nvm 플러그인을 통해 자동 완성을 얻는 경우와 같이 쉘 설정 파일 편집을 방지하도록 설치 프로그램에 지시할 수 있습니다. 이는 install.sh 스크립트를 실행하기 전에 PROFILE=/dev/null을 설정하여 수행할 수 있습니다. 이를 위한 한 줄 명령어 예시는 다음과 같습니다: PROFILE=/dev/null bash -c 'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash'
Docker에서 설치하기
Docker 컨테이너와 같이 비대화형 쉘로 bash를 호출할 때는 일반적인 프로필 파일이 소싱되지 않습니다. 따라서 nvm, node, 및 npm을 정상적으로 사용하려면, 비대화형으로 호출될 때 bash가 소싱하는 특별한 변수인 BASH_ENV를 지정할 수 있습니다.
# 쉘로 bash 사용
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
...
CI/CD 작업용 Docker 설치하기
더 강력하며, CI/CD 작업에서 작동합니다. 대화형 및 비대화형 컨테이너 모두에서 실행할 수 있습니다.
자세한 내용은 https://github.com/nvm-sh/nvm/issues/3531을 참조하십시오.
FROM ubuntu:latest
ARG NODE_VERSION=20
...
이 예시는 기본적으로 nodejs 버전 20.x.y로 설치됩니다. 선택적으로 다음과 같은 docker build 인수를 사용하여 버전을 쉽게 재정의할 수 있습니다:
docker build -t nvmimage --build-arg NODE_VERSION=19 .
이미지 생성 후 컨테이너를 대화형(interactively)으로 시작하고 명령을 실행할 수 있습니다. 예를 들면:
docker run --rm -it nvmimage
root@0a6b5a237c14:/# nvm -v
...
비대화형(Noninteractive) 예시:
user@host:/tmp/test $ docker run --rm -it nvmimage node -v
v19.9.0
user@host:/tmp/test $ docker run --rm -it nvmimage npm -v
...
Linux에서 문제 해결 (Troubleshooting on Linux)
Linux에서 설치 스크립트를 실행한 후 nvm: command not found 오류가 발생하거나, 터미널에 command -v nvm을 입력해도 아무런 피드백이 없다면, 현재 터미널을 닫고 새 터미널을 연 다음 다시 확인해 보세요.
대안으로, 명령줄에서 사용하는 다양한 셸(shell)의 경우 다음 명령어를 실행할 수 있습니다:
bash: source ~/.bashrc
zsh: source ~/.zshrc
ksh: . ~/.profile
이 명령어들이 nvm 명령을 불러올 것입니다.
macOS에서 문제 해결 (Troubleshooting on macOS)
OS X 10.9 버전부터 /usr/bin/git은 Xcode의 명령줄 도구(command line tools)에 의해 미리 설정되어 있어, Git이 설치되었는지 여부를 제대로 감지할 수 없습니다. 따라서 설치 스크립트를 실행하기 전에 Xcode 명령줄 도구를 수동으로 설치해야 합니다. 그렇지 않으면 실패합니다. (참고: #1782)
설치 스크립트 실행 후 nvm: command not found 오류가 발생했다면, 다음 중 하나가 원인일 수 있습니다:
-
macOS 10.15 버전부터 기본 셸(default shell)은 zsh이며 nvm은 업데이트를 위해 .zshrc 파일을 찾지만, 이 파일은 기본적으로 설치되지 않습니다. touch ~/.zshrc로 파일을 생성한 다음 설치 스크립트를 다시 실행하세요.
-
이전의 기본 셸이었던 bash를 사용하는 경우, 시스템에 명령이 설정된 .bash_profile 또는 .bashrc 파일이 없을 수 있습니다. touch ~/.bash_profile 또는 touch ~/.bashrc로 파일을 생성한 다음 설치 스크립트를 다시 실행하세요. 그런 다음, nvm 명령을 불러오기 위해 . ~/.bash_profile 또는 . ~/.bashrc를 실행하세요.
-
이전에 bash를 사용했지만, zsh가 설치되어 있습니다. 수동으로 이 줄들을 ~/.zshrc에 추가하고 . ~/.zshrc를 실행해야 합니다.
-
터미널 인스턴스를 재시작하거나 . ~/.nvm/nvm.sh를 실행해야 할 수도 있습니다. 터미널을 재시작하거나 새 탭/창을 열거나, 소싱(source) 명령을 실행하면 해당 명령어와 새로운 설정이 로드됩니다.
-
위의 방법으로도 해결되지 않는 경우, 터미널 인스턴스를 재시작해야 할 수 있습니다. 터미널에서 새 탭/창을 열어 다시 시도해 보세요.
위의 방법으로 문제가 해결되지 않으면 다음을 시도해 볼 수 있습니다:
-
bash를 사용하는 경우, .bash_profile (또는 ~/.profile)이 ~/.bashrc를 제대로 소싱(source)하지 못하고 있을 수 있습니다. 여기에 source ~/<your_profile_file>을 추가하거나 아래 다음 단계를 따름으로써 해결할 수 있습니다.
-
설치 섹션에서 찾은, 올바른 nvm 디렉토리를 찾아 nvm을 로드하는 설치 스니펫을 평소 사용하는 프로필 파일(~/.bash_profile, ~/.zshrc, ~/.profile, 또는 ~/.bashrc)에 추가해 보세요.
-
이 문제 및 가능한 해결책에 대한 자세한 정보는 여기를 참조하세요.
참고: Apple Silicon 칩이 장착된 Mac의 경우, node는 v16.0.0부터 arm64 아키텍처 Darwin 패키지를 제공하기 시작했으며, v14.17.0부터 소스 컴파일 시 실험적인 arm64 지원을 제공합니다. nvm을 사용하여 node를 설치하는 데 문제가 발생하면 해당 버전 또는 그 이후 버전으로 업데이트하는 것이 좋습니다.
Ansible
다음 태스크를 사용할 수 있습니다:
- name: Install nvm
ansible.builtin.shell: >
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash
...
설치 확인 (Verify Installation)
nvm이 성공적으로 설치되었는지 확인하려면 다음 명령을 실행하세요:
설치가 성공적이었다면 nvm이 출력되어야 합니다. 참고로, which nvm은 작동하지 않습니다. 이는 nvm이 실행 가능한 바이너리(executable binary)가 아니라 소싱된 셸 함수(sourced shell function)이기 때문입니다.
참고: Linux에서 설치 스크립트를 실행한 후, nvm: command not found 오류가 발생하거나 터미널에 command -v nvm을 입력해도 아무런 피드백이 보이지 않으면, 현재 터미널을 닫고 새 터미널을 연 다음 다시 확인해 보세요.
중요 참고 사항 (Important Notes)
만약 미리 패키징된 바이너리가 없는 시스템을 사용하고 있다면(즉, node 또는 io.js를 소스 코드에서 설치해야 하는 경우), 시스템에 C++ 컴파일러가 있는지 확인해야 합니다. OS X의 경우 Xcode를 사용하면 되고, Debian/Ubuntu 기반 GNU/Linux의 경우 build-essential 및 libssl-dev 패키지를 사용합니다.
