Next.js Debugging 가이드 정리

1. 개요

Next.js 디버깅 가이드는 다음 내용을 다룹니다.

VS Code 디버거를 사용해 서버/클라이언트/풀스택 디버깅하기
JetBrains WebStorm 디버거 사용하기
Chrome / Firefox DevTools로 클라이언트·서버 코드 디버깅하기
React Developer Tools로 React 컴포넌트 디버깅하기
Windows 환경에서 Fast Refresh 성능 문제를 줄이기 위한 팁

핵심은 Node.js 디버거가 붙을 수 있는 모든 도구를 Next.js에도 그대로 사용할 수 있다는 점입니다.

2. VS Code로 디버깅

프로젝트 루트에 .vscode/launch.json 파일을 만들고 다음과 같이 설정합니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev -- --inspect"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

패키지 매니저에 따라 npm run dev는 yarn dev, pnpm dev로 변경할 수 있습니다.
Next.js: debug full stack 설정에서 serverReadyAction.action 값은 디버깅에 사용할 브라우저를 지정합니다.
- Edge를 사용하려면 debugWithEdge
- Chrome을 사용하려면 debugWithChrome
개발 서버 포트를 변경했다면 http://localhost:3000 부분의 포트 번호를 현재 프로젝트 포트에 맞게 수정해야 합니다.
모노레포(Turborepo 등)에서 Next.js 앱이 루트가 아닌 서브 폴더에 있다면, cwd를 추가합니다.
- 예: "cwd": "${workspaceFolder}/apps/web"

설정을 저장한 후 VS Code의 Run and Debug 패널에서 원하는 설정을 선택하고 F5 또는 Command Palette의 Debug: Start Debugging으로 디버그 세션을 시작합니다.

3. JetBrains WebStorm 디버거 사용

상단의 런타임 구성 드롭다운에서 Edit Configurations...를 선택합니다.
JavaScript Debug 구성을 새로 만들고 URL을 http://localhost:3000으로 설정합니다.
사용할 브라우저, 프로젝트 파일 저장 여부 등을 원하는 대로 설정합니다.
해당 설정을 실행하면 브라우저가 자동으로 열리고, Node 서버와 브라우저 둘 다 디버깅이 활성화됩니다.

4. 브라우저 DevTools로 디버깅

4.1 클라이언트 코드 디버깅

next dev / npm run dev / yarn dev 등으로 개발 서버를 시작합니다.
브라우저에서 http://localhost:3000을 연 뒤 개발자 도구를 엽니다.
- Chrome: Ctrl+Shift+J (Windows/Linux), ⌥+⌘+I (macOS)
- Firefox: Ctrl+Shift+I (Windows/Linux), ⌥+⌘+I (macOS)
Chrome에서는 Sources 탭, Firefox에서는 Debugger 탭에서 소스를 확인합니다.
코드 중간에 debugger 구문을 넣거나, DevTools에서 직접 브레이크포인트를 설정하면 해당 지점에서 실행이 멈춥니다.
파일 검색 단축키:
- Chrome: Ctrl+P / ⌘+P
- Firefox: Ctrl+P / ⌘+P 또는 좌측 파일 트리
번들된 소스의 경로는 webpack://_N_E/./로 시작하는 형태로 표시됩니다.

4.2 React Developer Tools

React 컴포넌트 단위로 디버깅하려면 React Developer Tools 브라우저 확장을 설치합니다.

React 컴포넌트 트리를 탐색
props / state 값을 실시간으로 확인·수정
렌더링 성능 문제 파악

5. 서버 코드 디버깅 (브라우저 DevTools 사용)

Next.js 서버 코드를 브라우저 DevTools로 디버깅하려면 Node Inspector를 활성화해야 합니다.

next dev --inspect

--inspect는 내부적으로 Node.js 플래그로 전달됩니다.
원격 디버깅(예: Docker 컨테이너 내부에서 실행)을 허용하려면:

next dev --inspect=0.0.0.0

개발 서버를 위와 같이 띄우면 터미널에 다음과 유사한 메시지가 출력됩니다.

Debugger listening on ws://127.0.0.1:9229/...
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

이제 브라우저에서 Node 프로세스에 접속할 수 있습니다.

Chrome:
1. 새 탭에서 chrome://inspect 입력
2. Remote Target 아래에서 Next.js 애플리케이션 찾기
3. inspect 버튼을 눌러 별도의 DevTools 창 열기
Firefox:
1. 새 탭에서 about:debugging 입력
2. 좌측에서 This Firefox 선택
3. Remote Targets에서 Next.js 애플리케이션 찾기
4. Inspect 클릭 후 Debugger 탭으로 이동

주의 사항

--inspect-brk 또는 --inspect-wait를 사용하려면 NODE_OPTIONS 환경 변수에 설정해야 합니다.

NODE_OPTIONS=--inspect-brk next dev

6. 에러 오버레이에서 서버 에러 검사

Next.js 개발 중 에러가 발생하면 화면에 에러 오버레이가 뜹니다.

오버레이 우측 상단의 Next.js 버전 표시 아래에 Node.js 아이콘이 나타납니다.
이 아이콘을 클릭하면 서버 프로세스용 DevTools URL이 클립보드에 복사됩니다.
새 탭에서 해당 URL을 열면 Node.js 서버 코드의 원본 위치를 포함한 자세한 정보를 확인할 수 있습니다.

7. Windows에서 디버깅 시 주의점

Windows 환경에서는 Windows Defender와 같은 실시간 바이러스 검사 프로그램이 파일 읽기 속도를 크게 저하시켜 Fast Refresh가 느려질 수 있습니다.

next dev 실행 시 Fast Refresh가 비정상적으로 느리다면, 개발 환경에 한해 실시간 검사 기능을 꺼두는 것이 권장됩니다.

# Next.js Debugging 가이드 정리