Node.js 백엔드
로컬 실행 가이드

이 가이드는 개발 경험이 많지 않은 분을 위해 작성됐어요. 명령어의 의미를 몰라도 괜찮으니, 안내된 순서대로 따라해 주세요.

진행할 작업은 두 가지예요. 컴퓨터에 Node.js를 설치하고, 결제 서버를 실행해요. 이 문서는 백엔드 서버를 띄우는 가이드이며, 결제 테스트 화면(프론트엔드)은 다루지 않아요.

미리 알아둘 용어

Node.js를 컴퓨터에 설치해요. 이미 설치되어 있다면 이 단계는 건너뛰어도 돼요.

설치 따라하기

1. 다운로드
   웹 브라우저에서 nodejs.org에 접속한 뒤, "LTS" 버튼(권장 버전)을 클릭해 설치 파일을 받아 주세요. LTS는 안정적인 장기 지원 버전을 의미해요.
2. 설치
   받은 파일을 실행하고 기본 옵션 그대로 "Next" → "Install"을 눌러 설치해요. Windows와 Mac 모두 별도로 설정을 바꿀 필요가 없어요.
3. 설치 확인
   터미널을 새로 열고 아래 두 줄을 입력해 주세요. 각각 버전 숫자(예: v22.x.x / 10.x.x)가 표시되면 완료예요.

   terminal복사

   node --version
   npm --version

이제 서버를 실행해요. 아래 순서를 그대로 따라해 주세요. 명령은 한 줄씩 복사해 터미널에 붙여넣고 Enter를 누르시면 돼요.

1. 터미널 열기
   Windows는 PowerShell, Mac은 터미널 앱을 열어 주세요.
2. 프로젝트 폴더로 이동
   프로젝트를 저장한 폴더 안의 node 폴더로 이동해요. 아래의 <프로젝트 폴더> 부분을 본인이 저장한 실제 경로로 바꿔 주세요.

   terminal복사

   cd "<프로젝트 폴더>/node"

   경로 입력이 익숙하지 않다면, 터미널에 cd (cd 뒤에 공백 한 칸)를 입력한 뒤 node 폴더를 터미널 창으로 드래그해 주세요. 경로가 자동으로 채워져요. Windows는 폴더에서 Shift + 우클릭 → "경로로 복사" 후 붙여넣기 하시면 돼요.
3. 필요한 패키지 설치 (최초 1회)
   이 프로젝트가 사용하는 패키지(Express 등)를 한 번에 다운로드해요. 완료까지 잠시 기다려 주세요.

   terminal복사

   npm install

4. 서버 실행
   아래 한 줄로 서버가 실행돼요. Windows · Mac · Linux 모두 동일해요.

   terminal복사

   npm start

5. 서버 실행 확인
   터미널에 KCP 테스트 서버 실행: http://localhost:3000 같은 메시지가 표시되면 서버가 실행된 거예요. 더 확실한 확인 방법은 다음 04를 참고해 주세요.

이 문서는 서버(백엔드) 실행을 위한 가이드예요. 화면(프론트엔드)이 아닌 서버의 정상 실행 여부를 응답으로 확인해요.

확인 방법

방법 1 · 터미널 메시지: 서버를 실행한 터미널에서 KCP 테스트 서버 실행: http://localhost:3000 같은 줄이 보이면 서버가 실행된 거예요.

방법 2 · 응답 확인: 브라우저 주소창에 http://localhost:3000/config를 입력하거나, 새 터미널에서 아래 명령을 실행해 주세요. {"site_cd":"T0000"}와 같은 응답이 표시되면 서버와 라우팅이 정상 동작하는 거예요.

curl http://localhost:3000/config

실행 중 자주 만나게 되는 문제와 해결 방법이에요. 대부분 Node.js의 PATH 문제이거나, 패키지 설치를 빠뜨렸거나, 포트가 이미 사용 중이어서 발생해요.

증상별 해결법

테스트가 끝나면 다음 방법으로 서버를 종료해 주세요.

서버가 동작 중인 터미널 창에서 Ctrl + C를 눌러 주세요. Mac도 동일해요. 서버가 종료되며, 터미널이 다시 명령을 입력할 수 있는 상태로 돌아와요.