콘텐츠로 이동
HagiCodeHagicode Docs

언어 선택

현재 언어: 한국어

Node.js 설치

페이지 편집

이 페이지에서는 Windows, macOS, Linux에 Node.js를 설치하는 방법을 설명합니다. Desktop과 Microsoft Store 버전은 더 이상 Node.js를 내장하지 않고 시스템의 node와 npm을 그대로 사용하며, OpenSpec과 대부분의 Agent CLI도 이에 의존합니다.

버전 요구 사항

Node.js 24 이상이 필요하며, 최소 요구 사항도 24입니다. 보통은 최신 LTS 버전을 설치하면 됩니다. npm은 Node.js와 함께 설치되므로 따로 설치할 필요가 없습니다.

이 도구가 필요한 설치 방식

  • Microsoft Store / Desktop: 필요합니다. 시스템 PATH에서 node와 npm을 찾을 수 있어야 합니다.

Node.js 설치

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

  1. Node.js 공식 웹사이트에 접속합니다
  2. LTS(장기 지원) 버전의 Windows 설치 프로그램(.msi 파일)을 내려받고 버전이 24 이상인지 확인합니다
  3. 설치 프로그램을 더블 클릭해 실행합니다
  4. 설치 마법사의 안내에 따라 설치를 진행합니다.
    • 사용 계약에 동의합니다
    • 설치 경로를 선택합니다(기본값 그대로 두어도 됩니다)
    • “Add to PATH”가 선택된 상태를 유지합니다
    • “Install”을 클릭해 설치를 시작합니다
  5. 설치가 끝나면 “Finish”를 클릭합니다

방법 2: winget 사용

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

终端窗口
winget install OpenJS.NodeJS.LTS

설치가 끝나면 변경 사항이 적용되도록 터미널을 다시 엽니다.

버전 관리 도구 사용

여러 Node.js 버전 사이를 전환해야 한다면 버전 관리 도구를 사용할 수 있습니다.

Desktop 사용자 유의 사항

macOS와 Linux에서 nvm, fnm 같은 도구는 대개 셸 설정 파일(.bashrc, .zshrc 등)에서만 PATH를 설정합니다. Dock, 앱 메뉴, 바탕화면 아이콘에서 실행한 Desktop은 이 설정을 읽지 않아 node를 찾지 못할 수 있습니다. 버전 관리 도구를 사용한다면 이미 node를 실행할 수 있는 터미널에서 Desktop을 시작하거나, 위의 시스템 수준 설치 방법을 사용하세요.

nvm (Node Version Manager)

Linux/macOS

nvm 공식 저장소 README에 안내된 최신 설치 명령을 그대로 복사해 사용하고, 오래된 버전의 설치 스크립트 주소는 사용하지 마세요.

설치가 끝나면 셸 설정을 다시 불러옵니다.

终端窗口
source ~/.bashrc
# Zsh 사용자의 경우
source ~/.zshrc

Windows

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

  1. nvm-windows releases에서 최신 nvm-setup.exe를 내려받습니다
  2. 설치 프로그램을 실행합니다
  3. 명령 프롬프트 또는 PowerShell을 다시 엽니다

fnm (Fast Node Manager)

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

Linux/macOS

终端窗口
# curl로 설치
curl -fsSL https://fnm.vercel.app/install | bash


# 설치가 끝나면 셸 설정을 다시 불러오기
source ~/.bashrc
# Zsh 사용자의 경우
source ~/.zshrc

Windows

scoop 또는 winget을 사용합니다.

终端窗口
# scoop 사용
scoop install fnm


# 또는 winget 사용
winget install Schniz.fnm

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

중국 본토에서는 Node.js와 npm 패키지를 내려받는 속도가 느릴 수 있으며, 이때는 국내 미러를 사용할 수 있습니다.

npm 미러

终端窗口
# 미러를 일시적으로 사용해 설치
npm install --registry=https://registry.npmmirror.com


# 미러를 영구적으로 설정
npm config set registry https://registry.npmmirror.com


# 미러가 올바르게 설정되었는지 확인
npm config get registry

Node.js 설치 프로그램 미러

Node.js 설치 프로그램도 미러 다운로드 주소가 있습니다: https://npmmirror.com/mirrors/node/. 접속한 뒤 24 이상 버전을 선택해 내려받으세요.

Homebrew 미러

중국 본토에서 Homebrew를 사용한다면 bottle에 중국과학기술대학(USTC) 미러를 설정할 수 있습니다.

终端窗口
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

설치 확인

설치가 끝나면 새로 연 터미널에서 Node.js와 npm을 사용할 수 있는지 확인합니다.

终端窗口
# Node.js 버전 확인(v24.0.0 이상 필요)
node --version


# npm 버전 확인
npm --version

정상적인 출력은 다음과 비슷합니다.

$ node --version
v24.3.0


$ npm --version
11.4.2

node --version이 24 미만의 버전을 표시한다면 위의 방법으로 다시 설치하거나, 버전 관리 도구로 24 이상 버전으로 전환하세요.

npm 전역 디렉터리 설정

Desktop은 Agent CLI 같은 관리 대상 패키지를 로컬 npm의 전역 디렉터리에 설치합니다. 전역 디렉터리가 관리자 권한이 필요한 위치에 있으면 설치할 때 EACCES 권한 오류가 발생할 수 있습니다. 시스템 디렉터리의 권한을 수정하는 대신 전역 디렉터리를 사용자 디렉터리로 옮기는 것을 권장합니다.

终端窗口
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

그런 다음 ~/.npm-global/bin(Windows에서는 npm 전역 디렉터리 자체)을 시스템 PATH에 추가하고 터미널과 Desktop을 다시 시작합니다. nvm이나 fnm을 사용한다면 전역 디렉터리가 이미 사용자 디렉터리 아래에 있으므로 이 단계는 필요하지 않습니다.

문제 해결

Windows 문제

설치한 뒤 node 또는 npm 명령을 사용할 수 없는 경우:

  1. 명령 프롬프트 또는 PowerShell을 다시 시작합니다
  2. 그래도 사용할 수 없다면 Node.js를 PATH에 수동으로 추가합니다.
    • “환경 변수”를 검색해 “시스템 환경 변수 편집”을 엽니다
    • “환경 변수”를 클릭합니다
    • “시스템 변수”에서 “Path”를 찾아 “편집”을 클릭합니다
    • Node.js 설치 경로를 추가합니다(기본값: C:\Program Files\nodejs\)
    • “확인”을 클릭해 변경 사항을 저장합니다
  3. Desktop을 완전히 종료한 뒤 다시 시작합니다

macOS 문제

전역 npm 패키지를 설치할 때 권한 오류가 발생하면 위의 npm 전역 디렉터리 설정을 참고하거나 nvm / fnm을 대신 사용하세요.

Linux 문제

전역 npm 패키지를 설치할 때 권한 오류가 발생하면 위의 npm 전역 디렉터리 설정을 참고하거나, sudo로 전역 패키지를 설치하는 대신 nvm / fnm을 사용하세요.

환경 확인

확인에 실패하면 다음 내용을 점검하세요.

终端窗口
# Node.js가 PATH에 있는지 확인
where node


# 설치 경로 확인
Get-Command node

다음 단계

Node.js 설치를 마친 뒤에는 다음 단계를 이어서 진행할 수 있습니다.

설치 가이드로 돌아가기Git 등 사전 요구 사항을 마저 준비하고 사용 환경에 맞는 설치 방식을 선택합니다.
OpenSpec 소개OpenSpec 독립 문서 사이트에서 설치 방법, 핵심 개념, 명세 기반 워크플로를 확인합니다.
AI Agent CLI 설치현재 지원하는 Agent CLI의 공식 설치 진입점을 확인하고 원클릭 설치와 수동 설치 / 인증을 구분합니다.

도움이 더 필요하신가요?

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

  1. Node.js 공식 문서를 방문합니다
  2. Desktop이 사용자의 Node 환경을 사용하는 방식을 확인합니다
  3. HagiCode 제품 개요에서 현재 제품과 관련 도구 체인 설명을 확인합니다

HagiCode

HagiCode는 에이전트 코딩 작업 공간입니다. 풍부하고 편리한 UI 상호작용으로 계획 수립, 에이전트 실행, 프로젝트 작업을 쉽게 시작하고 따라가며 개발을 더 흥미로운 경험으로 만듭니다.

풍부하고 편리한 UI 상호작용으로 계획부터 프로젝트 작업까지 쉽게 따라갈 수 있습니다.

HagiCode 방문문서 읽기
  • 스마트OpenSpec 워크플로는 의도를 제안, 설계, 작업을 거쳐 배포까지 이어지는 실행 가능한 경로로 바꿉니다.
  • 효율적다중 에이전트 실행으로 조사, 구현, 검토를 병렬로 진행하며 여러 저장소와 익숙한 Agent CLI를 지원합니다.
  • 흥미로운풍부하고 편리한 UI 상호작용으로 계획 수립, 에이전트 실행, 프로젝트 작업을 쉽게 시작하고 따라갈 수 있습니다.

Windows용 다운로드

Microsoft Store에서 받기모든 다운로드

아이디어를 실제로 배포되는 소프트웨어로.

HagiCode는 에이전트 코딩 작업 공간입니다. OpenSpec 워크플로로 변경을 계획하고, 다중 에이전트 실행으로 진행하며, Hero Scenario로 긴 작업의 진행 상황을 한눈에 보여 아이디어를 실제로 배포되는 소프트웨어로 만듭니다.

HagiCode 다운로드제품 문서
스마트
OpenSpec 워크플로는 의도를 제안부터 배포까지 이어지는 실행 가능한 경로로 바꿉니다.
효율적
다중 에이전트 실행으로 조사, 구현, 검토를 병렬로 진행합니다.
즐거운
편리한 UI 상호작용으로 계획, 에이전트 실행, 프로젝트 작업을 쉽게 따라갈 수 있습니다.

© 2026 HagiCode | Powered By hagilight-starlight@0.20.0 | Branch: main | Commit: 0dde182 | Built: