> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js

Node.js는 JavaScript를 컴퓨터에서 직접 실행할 수 있게 해주는 런타임입니다. 서버 프로그램, 자동화 도구, 개발 도구 등을 실행할 수 있으며, 많은 개발 도구가 Node.js 기반으로 동작하므로 개발 환경 구축 시 필수적으로 설치하는 프로그램입니다.

## 사전 준비

* Windows 10 이상의 PC
* 인터넷 연결

<Steps>
  <Step title="Node.js 공식 웹사이트에 접속하기">
    웹 브라우저(크롬, 엣지 등)를 열고 주소창에 [nodejs.org](https://nodejs.org)를 입력하여 접속합니다.

    메인 페이지에 "Run JavaScript Everywhere"라는 문구와 함께 초록색 **Get Node.js** 버튼이 보입니다. 이 버튼을 클릭하면 다운로드 페이지로 이동합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/01-website.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=98f912da80756cc9843ed3397478ac88" alt="Node.js 공식 웹사이트" width="2560" height="1392" data-path="images/environment-setup/windows/nodejs/01-website.png" />
  </Step>

  <Step title="다운로드 페이지에서 설치 파일 받기">
    다운로드 페이지에서 LTS 버전의 Windows 설치 파일을 다운로드합니다.

    화면에 초록색 **Windows 설치 프로그램 (.msi)** 다운로드 버튼이 있습니다. 이 버튼을 클릭합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/02-download-page.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=5fba29de83f233c1e69f142b4619184f" alt="다운로드 페이지 - 설치 방법 안내" width="2560" height="1392" data-path="images/environment-setup/windows/nodejs/02-download-page.png" />

    <Tip>
      **LTS**는 "Long Term Support"의 약자로, 장기 지원 안정 버전입니다. 최신 기능이 포함된 Current 버전도 있지만, 안정성이 중요한 경우 LTS 버전을 선택하는 것이 좋습니다.
    </Tip>
  </Step>

  <Step title="설치 마법사 시작하기">
    다운로드한 .msi 파일을 더블클릭하여 실행합니다.

    "Welcome to the Node.js Setup Wizard"라는 환영 화면이 나타납니다. 이 화면은 설치를 시작하겠다는 안내 페이지입니다.

    하단의 **Next** 버튼을 클릭하여 다음 단계로 진행합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/03-setup-welcome.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=364a1ac05f1c3b9bb72a9f4f6db53621" alt="설치 마법사 시작" width="495" height="387" data-path="images/environment-setup/windows/nodejs/03-setup-welcome.png" />
  </Step>

  <Step title="라이선스에 동의하기">
    라이선스 계약(End-User License Agreement) 화면이 나타납니다. Node.js는 무료 오픈소스 소프트웨어이므로 안심하고 동의해도 됩니다.

    화면 하단에 있는 **"I accept the terms in the License Agreement"** 체크박스를 클릭하여 체크 표시를 합니다. 체크하지 않으면 Next 버튼이 활성화되지 않습니다.

    체크한 후 **Next** 버튼을 클릭합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/04-eula-accepted.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=d71ca7a74d50bb7629d60ff09dc1519d" alt="라이선스 동의" width="495" height="387" data-path="images/environment-setup/windows/nodejs/04-eula-accepted.png" />
  </Step>

  <Step title="설치 경로 선택하기">
    Node.js가 설치될 폴더를 지정하는 화면입니다. 기본값은 `C:\Program Files\nodejs\`로 설정되어 있습니다.

    특별한 이유가 없다면 기본 경로를 그대로 사용하는 것을 권장합니다. 경로를 변경하고 싶다면 **Change...** 버튼을 눌러 원하는 위치를 선택할 수 있습니다.

    **Next** 버튼을 클릭합니다.

    !\[설치 경로 선택 - C:\Program Files\nodejs]\(/images/environment-setup/windows/nodejs/05-destination-folder.png)
  </Step>

  <Step title="설치할 구성 요소 확인하기">
    어떤 기능들을 설치할지 선택하는 "Custom Setup" 화면입니다. 기본적으로 모든 항목이 선택되어 있으며, 그대로 두는 것이 좋습니다.

    각 항목의 의미는 다음과 같습니다:

    * **Node.js runtime** - Node.js 본체입니다. 반드시 필요합니다.
    * **corepack manager** - yarn 같은 패키지 관리 도구를 편리하게 사용할 수 있게 해줍니다.
    * **npm package manager** - Node.js용 라이브러리(패키지)를 설치하고 관리하는 도구입니다. 반드시 필요합니다.
    * **Online documentation shortcuts** - 공식 문서 바로가기를 시작 메뉴에 추가합니다.
    * **Add to PATH** - 어떤 폴더에서든 `node`, `npm` 명령어를 사용할 수 있게 해줍니다. 반드시 필요합니다.

    모든 항목이 선택된 상태에서 **Next** 버튼을 클릭합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/06-custom-setup-components.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=2be85b8b04f1991cda4172d0a7f316ee" alt="구성 요소 선택 - runtime, corepack, npm, docs, PATH" width="495" height="387" data-path="images/environment-setup/windows/nodejs/06-custom-setup-components.png" />
  </Step>

  <Step title="네이티브 모듈 도구 설치 옵션 확인하기">
    "Tools for Native Modules"라는 화면이 나타납니다. 일부 Node.js 패키지는 C/C++ 코드를 컴파일해야 하는데, 이를 위한 추가 도구(Python, Visual Studio Build Tools)를 자동으로 설치할지 묻는 화면입니다.

    "Automatically install the necessary tools" 체크박스가 있습니다. 이것은 **체크하지 않아도 됩니다**. 대부분의 경우 이 도구 없이도 Node.js를 충분히 사용할 수 있습니다. 나중에 필요할 때 별도로 설치할 수 있습니다.

    **Next** 버튼을 클릭합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/07-native-modules-tools.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=60482e16ed3b627dcb38386f5162ad96" alt="네이티브 모듈 도구 설치 옵션" width="495" height="387" data-path="images/environment-setup/windows/nodejs/07-native-modules-tools.png" />

    <Note>
      만약 나중에 `node-gyp` 관련 오류가 발생한다면, 그때 Python과 Visual Studio Build Tools를 설치하면 됩니다. 지금 단계에서는 건너뛰어도 괜찮습니다.
    </Note>
  </Step>

  <Step title="설치 시작하기">
    "Ready to install Node.js"라는 화면이 나타납니다. 지금까지 선택한 모든 설정을 확인하는 마지막 단계입니다.

    설정을 변경하고 싶다면 **Back** 버튼으로 이전 단계로 돌아갈 수 있습니다. 모든 설정이 맞다면 **Install** 버튼을 클릭하여 설치를 시작합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/09-ready-to-install.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=8f62be80623bbf0fffc9ad5d04ae4985" alt="설치 준비 완료" width="495" height="387" data-path="images/environment-setup/windows/nodejs/09-ready-to-install.png" />

    <Note>
      이때 Windows에서 "이 앱이 디바이스를 변경하도록 허용하시겠습니까?"라는 팝업이 나타날 수 있습니다. **예**를 클릭합니다.
    </Note>
  </Step>

  <Step title="설치 진행">
    "Installing Node.js"라는 화면과 함께 초록색 진행 바가 표시됩니다. "Status: Copying new files"라는 메시지가 보이면서 파일들이 복사됩니다.

    보통 1\~2분 정도 소요됩니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/10-installing.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=13812085f59bf9f8466f9b5b83f953c3" alt="설치 진행 중 - Copying new files" width="495" height="387" data-path="images/environment-setup/windows/nodejs/10-installing.png" />

    <Warning>
      설치 중에 창을 닫거나 Cancel 버튼을 누르면 설치가 중단됩니다. 진행 바가 완료될 때까지 대기합니다.
    </Warning>
  </Step>

  <Step title="설치 완료 확인하기">
    "Completed the Node.js Setup Wizard"라는 화면이 나타나면 설치가 성공적으로 완료된 것입니다. "Node.js has been successfully installed."라는 메시지를 확인합니다.

    **Finish** 버튼을 클릭하여 설치 마법사를 종료합니다.

    <img src="https://mintcdn.com/ddok/yHFODUwLjj9G9z4I/images/environment-setup/windows/nodejs/11-install-complete.png?fit=max&auto=format&n=yHFODUwLjj9G9z4I&q=85&s=7f72e5513f185c838c3d0d2015946dec" alt="설치 완료" width="495" height="387" data-path="images/environment-setup/windows/nodejs/11-install-complete.png" />
  </Step>
</Steps>

## 설치 확인하기

터미널(PowerShell)을 열고 다음 명령어를 입력하여 설치를 확인합니다.

```powershell theme={null}
node --version
npm --version
```

각각 `v22.x.x` (Node.js 버전)와 `10.x.x` (npm 버전) 같은 버전 번호가 출력되면 설치가 정상적으로 완료된 것입니다.

<Tip>
  PowerShell을 여는 방법: 키보드에서 `Windows 키`를 누르고 "PowerShell"을 입력한 후 Enter를 누르면 됩니다.
</Tip>

<Warning>
  만약 "node는 인식할 수 없는 명령입니다"라는 오류가 나온다면, 터미널을 완전히 닫고 새로 열어 보세요. 설치 후 터미널을 재시작해야 PATH(경로) 설정이 적용됩니다.
</Warning>

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 문제 해결 가이드

* 설치 파일이 실행되지 않으면 관리자 권한으로 다시 실행합니다.
* 명령어가 인식되지 않으면 터미널을 새로 열고 PATH 반영 여부를 확인합니다.
* 버전이 맞지 않으면 기존 설치를 정리한 뒤 권장 버전으로 재설치합니다.
* 설정 변경 후 동작이 이상하면 시스템 재시작 후 다시 확인합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: uv (Python 패키지 매니저)" icon="arrow-right" href="/setup/windows/uv-python">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>