Node.js 설치

이 페이지의 목표 — bkit과 우리 튜토리얼 프로젝트가 동작하는 데 필요한 Node.js를 설치합니다.

Node.js는 다음 단계인 bkit 설치 전에 반드시 있어야 해요. bkit의 자동화 기능(hook)이 Node.js로 동작하거든요.

왜 Node.js가 필요해요?

Node.js는 두 가지 일에 쓰여요.

1. bkit의 자동화 엔진 — bkit이 "특정 이벤트가 일어났을 때 자동으로 실행"하는 hook 스크립트를 Node.js로 돌립니다. 예: 코드 수정 → 자동으로 설계 문서랑 맞는지 검사, 작업 끝 → 자동으로 보고서 생성
2. 튜토리얼 프로젝트 실행 — 우리가 만들 라이프 위키(Astro 기반 웹사이트)를 내 컴퓨터에서 띄워보고 수정할 때 Node.js가 필요해요

비유로 이해하기 — Node.js 없이 bkit을 설치하는 건 자동변속기 없는 차를 사는 거예요. 설치는 되고 명령어도 입력되지만, 핵심 자동화 기능이 동작하지 않아요. 그래서 bkit 설치 전에 먼저 Node.js부터 깔아둡니다.

시작 전 준비물

• VS Code 설치 완료 (아직이면 VS Code 설치 페이지부터)
• Claude Code 설치 완료 (아직이면 Claude Code 설치 페이지부터)

STEP 1. Node.js가 이미 설치돼 있는지 확인

다른 도구를 깔다가 같이 들어왔을 수도 있어요. 먼저 확인부터 합니다.

1. VS Code에서 터미널 열기 (Ctrl + `)
2. 아래 명령어 두 줄 입력 (한 줄씩)

node -v
npm -v

두 줄 모두 버전 번호가 나오면 이미 설치된 상태예요. 예시:

v22.11.0
10.9.0

버전 확인 기준:

• node -v가 v18 이상이면 OK — bkit 사용 가능 (권장은 v22 LTS 또는 v24 LTS)
• v16 이하거나 명령어가 인식되지 않으면 STEP 2로 가서 설치

"'node'은(는) 내부 또는 외부 명령이 아닙니다" 같은 메시지가 뜨면 아직 설치 안 된 상태예요.

STEP 2. Node.js 설치 — AI에게 물어보기

이미 깔려있고 v18 이상이면 STEP 2는 건너뛰어도 돼요. 없거나 너무 낮은 버전이면 설치를 진행합니다.

먼저 VS Code AI에게 물어보세요

우측 에이전트 패널에 아래 프롬프트를 그대로 복사해서 붙여넣어 보세요.

Node.js를 설치하고 싶어요. 나는 Windows를 쓰고 있어요.

LTS(장기 지원) 버전으로 설치하려고 해요.
공식 사이트(nodejs.org)에서 다운로드해서 설치하는 방법을
단계별로 알려주세요.

설치가 끝나면 잘 됐는지 어떻게 확인하는지도 함께 알려주세요.

AI가 단계별로 안내해줄 거예요. 그 설명을 따라 진행하면 됩니다.

모범답안 (잘 안 되면 참고)

1. 브라우저에서 nodejs.org 접속
2. 홈 화면에 LTS 라벨이 붙은 큰 다운로드 버튼이 보임 — 클릭
3. 다운로드된 .msi 파일 더블클릭
4. 설치 마법사가 뜨면 모두 기본값(Next)으로 진행 — 중간에 옵션 바꿀 게 없음
5. 마지막에 "Tools for Native Modules" 체크박스가 나오는데, 우리 스터디에선 체크 안 해도 됨 (체크하면 추가 도구도 같이 설치돼서 시간이 더 걸려요)
6. 설치 끝나면 VS Code를 완전히 닫았다가 다시 열기 (PATH 환경변수 갱신을 위해)

중요 — 설치 후 VS Code를 새로 열지 않으면 터미널이 새 Node.js를 못 찾을 수 있어요. 꼭 한 번 종료 후 다시 실행하세요.

다른 OS는 어떻게 하나요?

STEP 3. 설치 확인

VS Code를 다시 연 다음, 터미널에서 한 번 더 확인합니다.

node -v
npm -v

두 줄 다 버전 번호가 나오면 성공이에요.

v22.x.x
10.x.x

버전 번호의 첫 숫자(v22, v24 등)가 18 이상이면 됩니다. 정확한 숫자는 설치 시점에 따라 달라요.

아직 명령어가 인식되지 않으면? VS Code를 한 번 더 완전히 종료(트레이까지)했다가 다시 실행해보세요. 그래도 안 되면 컴퓨터를 재시작하면 보통 해결됩니다.

다음 단계

Node.js 설치가 끝났어요. 이제 마지막으로 bkit 설치로 넘어가서 자동화 도구까지 갖추면 환경 세팅이 완전히 끝납니다.