Node.js API Guide 01 — 개발환경 세팅 (Windows) | 0xccffff Log

01 — 개발환경 세팅 (Windows): Node.js 24 LTS + VS Code + 첫 확인#

이 글에서는 실습을 위한 최소 개발환경을 준비합니다.

Note

이 글이 끝나면

터미널에서 명령어를 실행할 수 있고
Node.js / npm 설치가 확인되며
VS Code에서 프로젝트 폴더를 열 수 있습니다.

준비물#

Windows 11 (권장)
인터넷 연결
설치 권한(설치 과정에서 관리자 권한이 필요할 수 있음)

테스트 환경: Windows 11, Node.js 24 LTS

0) 작업 폴더 위치 고정하기#

이 시리즈는 아래 경로로 통일합니다.

C:\Workspace\node-api

Warning

처음부터 꼬이는 대표 원인

바탕화면 / 문서 / 다운로드 / OneDrive 동기화 폴더에서 시작함
경로에 한글/공백/특수문자가 너무 많음

가능하면 C:\Workspace\node-api로 시작하세요.

1) Node.js 설치 (24 LTS)#

Node.js는 서버를 실행하는 도구입니다. 이 시리즈는 24 LTS 기준으로 진행합니다.
설치가 끝나면 Windows Terminal(PowerShell)에서 버전 확인까지 합니다.

1-1) 다운로드 페이지 열기#

브라우저에서 Node.js 공식 다운로드 페이지로 이동합니다.
보통은 Windows x64 Installer (.msi) 를 받으면 됩니다.

Node.js 다운로드

1-2) 설치 파일 실행#

받은 .msi 파일을 실행합니다.

Node.js 설치 시작

1-3) 라이센스 동의#

License 동의 → Next

Node.js 라이센스 동의

1-4) 설치 경로#

기본값으로 둡니다.

Node.js 설치 경로

1-5) 설치 옵션#

설치 옵션도 기본값으로 둡니다.

Node.js 설치 옵션

1-6) Tools for Native Modules?#

Troubleshooting

“Tools for Native Modules”는 꼭 해야 하나요?

이 시리즈(간단한 API 서버)는 보통 필요 없습니다.
설치 화면에서 해당 옵션은 일단 체크하지 않고 진행해도 됩니다.

다만 나중에 npm install 중 아래 메시지가 나오면(예: node-gyp, Python, Visual Studio Build Tools), 그때는 Node 설치 프로그램을 다시 실행해서 Tools for Native Modules를 설치하거나, 필요한 빌드 도구(파이썬/컴파일러)를 추가로 설치하면 해결됩니다.
(대표적으로 sharp, sqlite3, canvas 같은 패키지에서 필요할 수 있습니다.)

아래와 같이 진행합니다.

Node.js Tools for Native Modules

1-7) 설치#

Install 버튼을 누릅니다.

Node.js 설치

1-8) 설치 완료#

설치가 끝나면 Finish로 종료합니다.

Node.js 설치 완료

1-9) 설치 확인 (중요)#

설치 후에는 Terminal 앱을 열고(이미 열려 있다면 닫았다가 다시 열고) 아래를 입력합니다. (기본으로 PowerShell이 열리면 그대로 따라오면 됩니다.)

(잠깐) 터미널(Terminal)이 뭐고, 어디서 여나요?#

터미널은 명령어를 입력하는 창입니다.
이 글에서는 설치 확인(node -v, npm -v)과 폴더 만들기에 사용합니다.

시작 메뉴에서 Terminal 검색 → 실행
또는 Win + X → Terminal

Expected result

기본으로 PowerShell이 열리면 그대로 따라오면 됩니다. (보통 PS C:\>처럼 보입니다.)

Note

중요: 이 글은 기본적으로 상단 탭에 “Windows PowerShell”이라고 적힌 창을 기준으로 진행합니다.

npm.ps1 실행 정책 오류는 PowerShell 전용 이슈이므로,
다른 셸(Command Prompt, Git Bash 등)을 사용하는 경우
오류 메시지가 다르게 보일 수 있습니다.

node -v
npm -v

Expected result

node -v → v24.x.x 같은 버전이 출력됨
npm -v → 버전 숫자가 출력됨

node/npm 버전 확인

Troubleshooting

npm 실행 시 “running scripts is disabled” 오류가 나요 (PowerShell)

예시: npm : ...\npm.ps1 cannot be loaded because running scripts is disabled on this system

이건 PowerShell 실행 정책(Execution Policy) 때문에 npm.ps1 실행이 막힌 경우입니다.

해결 방법 A (추천): 현재 사용자만 허용으로 변경#

Terminal(PowerShell)에서 아래를 실행합니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

실행 후 Terminal을 완전히 닫았다가 다시 열고, 다시 확인합니다.

npm -v

해결 방법 B (임시): 이번 터미널에서만 우회#

회사/학교 PC처럼 정책 변경이 어려우면, 이번 창에서만 임시로 우회할 수 있습니다.

Set-ExecutionPolicy -Scope

Troubleshooting

node가 인식되지 않음 (가장 흔함)

증상: node is not recognized... 같은 메시지
해결 순서:
1. Terminal(또는 PowerShell)을 완전히 종료 후 다시 실행
2. 그래도 안 되면 PC 재부팅
3. 그래도 안 되면 Node.js를 다시 설치(24 LTS)

2) VS Code 설치#

VS Code는 코드 편집기입니다. 이 시리즈에서는 코드를 작성/수정하고, 프로젝트 폴더를 열기 위해 사용합니다.

2-1) 다운로드 페이지 열기#

브라우저에서 VS Code 공식 다운로드 페이지로 이동합니다.
보통은 User Installer (x64) 를 받으면 됩니다.

VS Code 다운로드

2-2) 설치 파일 실행#

받은 설치 파일을 실행합니다.

VS Code 설치 시작

2-3) 설치 경로#

설치 경로는 기본값으로 둡니다.
Next로 진행합니다.

VS Code 설치 경로

시작 메뉴 폴더도 기본값으로 둡니다.
Next로 진행합니다.

VS Code Select Start Menu Folder

2-5) 설치 옵션#

설치 옵션에서 아래 항목은 체크 추천입니다.

✅ Add to PATH (터미널에서 code . 명령을 쓰고 싶으면 추천)
✅ Add "Open with Code" action (우클릭으로 VS Code 열기)
✅ Register Code as an editor for supported file types (기본 편집기로 등록)

VS Code 설치 옵션

2-6) 설치#

Install을 눌러 설치를 진행합니다.

VS Code 설치

2-7) 설치 완료#

아래처럼 완료 화면이 나오면 설치가 끝난 것입니다.
Finish를 눌러 종료합니다.
(선택) “Launch Visual Studio Code” 같은 체크가 있다면 켜둬도 됩니다.

VS Code 설치 완료

2-8) 실행 확인#

VS Code를 실행합니다.

Expected result

VS Code가 열리고 상단 메뉴/좌측 사이드바가 보이면 OK

VS Code 첫 실행 화면

Troubleshooting

code .가 안 먹는 경우

먼저 Terminal 앱을 완전히 닫았다가 다시 열고 다시 시도해 보세요.
그래도 안 되면 VS Code 설치 옵션에서 Add to PATH가 체크되지 않았을 가능성이 큽니다.
그래도 실습은 진행 가능합니다. 아래 방법 중 하나로 폴더를 열면 됩니다.

해결 방법 A (추천): 메뉴로 폴더 열기

VS Code → File > Open Folder... → C:\Workspace\node-api

해결 방법 B: 설치를 다시 실행해서 Add to PATH 체크

VS Code 설치 파일을 다시 실행하고, 옵션에서 Add to PATH를 체크한 뒤 다시 설치합니다.

3) 프로젝트 폴더 만들기#

Terminal(PowerShell)에서 아래를 그대로 실행합니다.
(이미 폴더가 있으면 mkdir에서 “이미 존재” 메시지가 나올 수 있는데, 정상입니다.)

cd C:\
mkdir Workspace\node-api
cd Workspace\node-api

Expected result

현재 위치가 C:\Workspace\node-api 입니다.

4) VS Code에서 폴더 열기#

방법 A) VS Code 메뉴로 열기 (확실한 방법)#

VS Code → File > Open Folder...
C:\Workspace\node-api 선택

Warning

주의: VS Code를 방금 설치했다면,
기존에 열려있던 터미널 창을 완전히 닫고 새로 열어야 code . 명령어가 인식됩니다. 설치 과정에서 PATH 환경 변수가 갱신되기 때문입니다.

방법 B) 터미널에서 열기 (가능한 경우)#

code .

Expected result

VS Code 왼쪽 탐색기에서 node-api 폴더가 보이면 OK

5) 최종 체크#

아래가 되면 준비 완료입니다.

Terminal에서 아래 명령이 동작함

node -v
npm -v

VS Code에서 C:\Workspace\node-api 폴더를 열 수 있음

다음 글#

다음 글에서는 실제로 서버를 실행하고, 브라우저에서 JSON 응답을 확인합니다.

다음 글: 02. 서버 띄우기 (GET /health)