개요

Node.js 디버깅 환경은 V8 인스펙터 도입 이후 일관된 방식으로 수렴했음 Node.js v6부터 V8 네이티브 인스펙터가 들어왔고 v8.0.0에서 v8-inspector를 본격 지원하면서 기존 –debug는 폐기, –inspect로 통일됨 CLI 디버거 node-inspect가 코어에 통합되어 브라우저 개발자도구와 커맨드라인 중 선택 가능함

이 글은 Node.js 8 이상에서 동작하는 v8-inspector 기반 디버깅 플로우를 요약함

핵심 개념

  • v8-inspector 프로토콜
    • V8이 노출하는 디버깅 프로토콜
    • Node 프로세스가 WebSocket 엔드포인트를 열고 디버거가 여기에 연결하는 구조
  • –inspect vs –inspect-brk
    • –inspect는 바로 실행하면서 디버거 접속 대기
    • –inspect-brk는 첫 줄에서 일시정지 후 시작, 초기화 로직부터 추적할 때 유용
  • 포트
    • 기본 포트 9229 사용
    • –inspect=PORT, –inspect-brk=PORT 형태로 변경 가능
  • 프론트엔드
    • Chromium 기반 개발자도구로 연결 가능
    • chrome://inspect 에서 Node 대상 탐색 및 연결
  • node-inspect
    • Node 내장 CLI 디버거
    • 동일한 인스펙터 포트로 접속하여 터미널에서 스텝 실행과 REPL 수행

크롬 개발자도구로 디버깅

Express 같은 서버 앱을 예시로 실행 파일이 bin/www라고 가정

  • 서버를 인스펙터 모드로 시작
node --inspect bin/www
# Debugger listening on ws://127.0.0.1:9229/<uuid>
# For help see https://nodejs.org/en/docs/inspector
  • 브라우저에서 chrome://inspect 접속
    • Remote Target 목록에서 해당 Node 프로세스 확인
    • inspect 버튼으로 개발자도구 연결
  • 디버깅 방법은 웹 프론트 디버깅과 동일
    • 브레이크포인트 설정, 콜스택 확인, 스텝 인/아웃, 워치, 콘솔 활용
  • 애플리케이션 시작 시점부터 멈추려면 –inspect-brk 사용

node-inspect로 터미널 디버깅

GUI 없이도 빠르게 문제를 추적할 때 유용

  • 디버거 시작
node inspect bin/www
# Debugger listening on ws://127.0.0.1:9229/<uuid>
# Debugger attached
# Break on start in bin/www:1
  • 기본 명령
    • cont, c 계속 실행
    • next, n 다음 라인으로 이동
    • step, s 함수 내부로 진입
    • out, o 호출한 함수로 빠져나오기
    • run, restart 프로세스 재시작
    • repl 현재 컨텍스트에서 표현식 실행
  • 브레이크포인트 팁
    • 코드에 debugger 구문을 삽입해 명시적 중단점으로 사용 가능

간단 예시

debug> cont
# ... debugger 구문에서 일시정지됨

debug> repl
Press Ctrl + C to leave debug repl
> console.log(app.settings)
< { env: 'development', 'view engine': 'jade', ... }
> undefined

경로 등 민감한 값은 출력 시 마스킹 권장

포트와 연결 관리

  • 기본 포트 9229 충돌 시 –inspect=9230 처럼 변경
  • 동일한 포트에 크롬 개발자도구 또는 node-inspect 중 하나만 독점 연결하지 않도록 유의
  • 원격 서버에서 사용할 경우 네트워크에 디버그 포트를 그대로 노출하지 않음
    • 신뢰 네트워크에서만 접속 허용 또는 포트포워딩, 터널링 사용 권장

운영 시 유의사항

  • –inspect는 성능에 약간의 오버헤드가 있을 수 있음
  • 프로덕션 상시 활성화는 지양, 재현 가능한 환경에서 일시적으로 활성화 권장
  • 초기화 코드 이슈 추적은 –inspect-brk가 더 안정적
  • 디버깅 세션 중 프로세스가 재시작되면 연결이 끊기므로 재연결 필요

정리

Node.js의 디버깅은 v8-inspector를 중심으로 표준화되었음 –inspect 또는 –inspect-brk로 프로세스를 띄우고, 크롬 개발자도구나 node-inspect 중 선호 도구로 연결해 브레이크포인트와 스텝 실행, REPL까지 한 흐름으로 해결 가능함 개발 단계에서 빠르게 재현하고 추적하는 기본 루틴으로 정착시키면 콘솔 로그만으로 놓치는 분기와 타이밍 이슈를 줄일 수 있음

참고자료

  • Node.js v8.0.0 Release
  • Debugging Node.js Apps with the Inspector
  • Node.js Debugger API
  • node-inspect Repository
  • Express

참고자료