콘텐츠로 이동
Hagicode Docs
블로그

Node.js 설치

페이지 편집

이 가이드에서는 Windows, macOS 및 Linux에서의 Node.js 설치를 다룹니다. Node.js는 OpenSpec, 프런트엔드 도구 및 여러 개발자 CLI를 포함한 HagiCode 로컬 도구의 주요 종속성입니다.

Node.js 설치

섹션 제목: “Node.js 설치”

방법 1: 공식 설치 프로그램(권장)

섹션 제목: “방법 1: 공식 설치 프로그램(권장)”
  1. 방문 Node.js 공식 웹사이트
  2. LTS(장기 지원) 버전 Windows 설치 프로그램을 다운로드합니다(.msi 파일)
  3. 설치 프로그램을 실행하려면 두 번 클릭하세요.
  4. 설치 마법사의 지시에 따라 설치를 완료합니다.
    • 라이센스 계약에 동의하세요
    • 설치 경로 선택(기본값이면 좋음)
    • “필요한 도구를 자동으로 설치”가 선택되어 있는지 확인하십시오
    • 설치를 시작하려면 “설치”를 클릭하세요.
  5. 설치가 완료되면 “마침”을 클릭하세요

방법 2: Winget 사용

섹션 제목: “방법 2: Winget 사용”

PowerShell 또는 명령 프롬프트를 열고 다음을 실행합니다.

Terminal window
winget install OpenJS.NodeJS.LTS

설치 후 변경 사항을 적용하려면 터미널을 다시 엽니다.

버전 관리 도구 사용

섹션 제목: “버전 관리 도구 사용”

여러 Node.js 버전 간에 전환해야 하는 경우 버전 관리 도구를 사용할 수 있습니다.

nvm(노드 버전 관리자)

섹션 제목: “nvm(노드 버전 관리자)”

리눅스/맥OS

섹션 제목: “리눅스/맥OS”
Terminal window
# Install using curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash


# Or install using wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

설치 후 셸 구성을 다시 로드합니다.

Terminal window
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

윈도우

섹션 제목: “윈도우”

Windows에서는 다음을 사용하는 것이 좋습니다. nvm-windows:

  1. 최신 다운로드 nvm-setup.exe 에서 nvm-windows 릴리스
  2. 설치 프로그램 실행
  3. 명령 프롬프트 또는 PowerShell 다시 열기

fnm (빠른 노드 관리자)

섹션 제목: “fnm (빠른 노드 관리자)”

fnm은 Rust로 구축된 더 빠르고 간단한 Node.js 버전 관리 도구입니다.

리눅스/맥OS

섹션 제목: “리눅스/맥OS”
Terminal window
# Install using curl
curl -fsSL https://fnm.vercel.app/install | bash


# After installation, reload shell configuration
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

윈도우

섹션 제목: “윈도우”

사용 국자 또는 날개:

Terminal window
# Use scoop
scoop install fnm


# Or use winget
winget install Schniz.fnm

중국 본토 사용자를 위한 가속화

섹션 제목: “중국 본토 사용자를 위한 가속화”

중국 본토에 거주하는 경우 Node.js 및 npm 패키지 다운로드가 느려질 수 있습니다. 다음은 몇 가지 가속 솔루션입니다.

국내 미러 소스 사용

섹션 제목: “국내 미러 소스 사용”

npm Taobao 미러(권장)

섹션 제목: “npm Taobao 미러(권장)”
Terminal window
# Temporarily use Taobao mirror
npm install --registry=https://registry.npmmirror.com


# Permanently set Taobao mirror
npm config set registry https://registry.npmmirror.com


# Verify mirror is set successfully
npm config get registry

nmm을 사용하여 미러 소스 관리

섹션 제목: “nmm을 사용하여 미러 소스 관리”

nrm(npm 레지스트리 관리자)은 npm 미러 소스를 빠르게 전환하는 데 도움이 됩니다.

Terminal window
# Install nrm
npm install -g nrm


# List available mirror sources
nrm ls


# Switch to Taobao mirror
nrm use taobao


# Test mirror source speed
nrm test

Node.js 설치 프로그램 다운로드 가속화

섹션 제목: “Node.js 설치 프로그램 다운로드 가속화”

Taobao는 Node.js 설치 프로그램을 위한 미러 다운로드를 제공합니다.

위 주소로 방문하셔서 다운로드가 필요한 버전을 선택하세요.

국내 홈브루 거울

섹션 제목: “국내 홈브루 거울”

중국 본토에서 Homebrew를 사용하는 경우 가속을 위해 국내 미러를 구성할 수 있습니다.

Terminal window
# Install Homebrew using domestic mirror
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"


# Or use USTC mirror
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

중국 본토 특정 패키지 관리자

섹션 제목: “중국 본토 특정 패키지 관리자”

cnpm

섹션 제목: “cnpm”

cnpm은 기본적으로 Taobao 미러를 사용하는 Taobao 팀에서 제공하는 npm 클라이언트입니다.

Terminal window
# Install cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com


# Use cnpm to install packages
cnpm install <package-name>

:::팁 cnpm은 대부분 npm 명령과 호환되며 직접 대체물로 사용할 수 있습니다. :::

거울 가속 효과 확인

섹션 제목: “거울 가속 효과 확인”

미러를 설정한 후 다음을 통해 확인하십시오.

Terminal window
# Test download speed
time npm install express --registry=https://registry.npmmirror.com


# Compare with official source speed
time npm install express --registry=https://registry.npmjs.org

설치 확인 중

섹션 제목: “설치 확인 중”

설치 후 Node.js와 npm이 올바르게 설치되었는지 확인하세요.

Terminal window
# Check Node.js version
node --version


# Check npm version
npm --version

:::참고 Node.js 버전이 18.0 이상인지 확인하세요(Node.js 24+ 권장). 버전이 너무 낮은 경우 위의 방법으로 다시 설치하거나 버전 관리 도구를 사용하여 올바른 버전을 설치하십시오. :::

샘플 검증 출력

섹션 제목: “샘플 검증 출력”

성공적인 확인 출력은 다음과 같습니다.

$ node --version
v24.3.0


$ npm --version
10.2.3

문제 해결

섹션 제목: “문제 해결”

윈도우 문제

섹션 제목: “윈도우 문제”

만약에 node 또는 npm 설치 후에는 다음 명령을 사용할 수 없습니다.

  1. 명령 프롬프트 또는 PowerShell 다시 시작
  2. 여전히 사용할 수 없는 경우 Node.js를 PATH에 수동으로 추가하세요.
    • “환경 변수”를 검색하고 “시스템 환경 변수 편집”을 엽니다.
    • “환경 변수”를 클릭하세요.
    • “시스템 변수”에서 “경로”를 찾아 “편집”을 클릭하세요.
    • Node.js 설치 경로 추가(기본값: C:\Program Files\nodejs\)
    • 변경 사항을 저장하려면 “확인”을 클릭하세요.

macOS 문제

섹션 제목: “macOS 문제”

글로벌 npm 패키지를 설치할 때 권한 오류가 발생하는 경우:

Terminal window
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

리눅스 문제

섹션 제목: “리눅스 문제”

글로벌 npm 패키지를 설치할 때 권한 오류가 발생하는 경우 시스템 패키지 관리자 대신 Node.js 버전 관리 도구(예: nvm 또는 fnm)를 사용하는 것이 좋습니다.

환경 확인

섹션 제목: “환경 확인”

확인에 실패하면 다음을 확인하세요.

Terminal window
# Check if Node.js is in PATH
where node


# Check installation path
Get-Command node

다음 단계

섹션 제목: “다음 단계”

Node.js 설치가 완료된 후 다음 단계를 계속할 수 있습니다.

Install OpenSpec Install the OpenSpec specification-driven development tool to manage proposals, specs, and changes.
Install AI Agent CLI Use one registry for the official install entries for Claude Code, Codex, Gemini, GitHub Copilot, CodeBuddy, OpenCode, Kimi, QoderCLI, and Kiro.
Return to Installation Guide Return to the main installation guide to continue configuring other dependencies.

도움이 더 필요하신가요?

섹션 제목: “도움이 더 필요하신가요?”

여기서 다루지 않은 문제가 발생하는 경우:

  1. 방문 Node.js 공식 문서
  2. 검토 HagiCode 제품 개요 현재 제품 및 도구 상황에 맞게
  3. 방문 하기코드 홈페이지 최신 지원 진입점에 대한 정보