How to use debugging tools with Next.js

김동현·2026년 3월 5일
docsnext.js

next.js 공식문서 번역

목록 보기
47/79

title: Next.js에서 디버깅 도구 사용하는 방법
description: VS Code, Chrome DevTools 또는 Firefox DevTools를 사용하여 Next.js 애플리케이션을 디버깅하는 방법을 배워봅시다.
url: "https://nextjs.org/docs/app/guides/debugging"
version: 16.1.6
lastUpdated: 2026-02-27
prerequisites:

안녕하세요, 예비 프론트엔드 개발자 여러분! 여러분의 학습을 도와줄 강사입니다.
웹 개발을 하다 보면 누구나 에러를 만나게 됩니다. 보통 에러가 나면 소스 코드 여기저기에 console.log만 잔뜩 찍어보시는 경우가 많죠? 하지만 Next.js처럼 클라이언트(브라우저)와 서버(Node.js)를 모두 다루는 복잡한 환경에서는 제대로 된 디버거(Debugger)를 쓸 줄 알아야 에러의 원인을 훨씬 정확하고 빠르게 찾을 수 있답니다. 퇴근 시간을 획기적으로 앞당겨주는 비법이기도 하죠!

오늘은 Next.js 공식 문서를 함께 살펴보며 디버깅의 세계로 안내해 드릴게요. 딱딱하게 번역만 하지 않고, 실무에서 제가 직접 겪으며 얻은 팁과 부연 설명도 팍팍 넣어드릴 테니 잘 따라와 주세요!

이 문서는 VS Code 디버거, Chrome DevTools(개발자 도구), 또는 Firefox DevTools를 사용하여 전체 소스 맵(source maps) 지원과 함께 Next.js 프론트엔드 및 백엔드 코드를 디버깅하는 방법을 설명합니다.

기본적으로 Node.js에 연결할 수 있는 디버거라면 무엇이든 Next.js 애플리케이션 디버깅에 사용할 수 있어요. 이에 대한 더 자세한 내용은 Node.js 디버깅 가이드 시작하기에서 확인하실 수 있습니다.

VS Code로 디버깅하기

VS Code는 프론트엔드 개발자들이 가장 사랑하는 에디터 중 하나죠. VS Code에 내장된 디버거를 사용하면 정말 편리하게 코드를 분석할 수 있습니다.

가장 먼저 할 일은 프로젝트 루트(최상위 폴더)에 .vscode/launch.json이라는 파일을 만들고 다음 내용을 그대로 붙여넣는 거예요.

💡 강사의 팁: launch.json은 VS Code에게 "내가 F5 키를 누르면, 여기 적힌 설정대로 내 프로젝트를 실행하고 디버깅 모드를 켜줘!"라고 알려주는 일종의 지시서랍니다. 

{
  "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}"
      }
    }
  ]
}

참고: VS Code에서 Firefox 디버깅을 사용하려면 Firefox Debugger 확장 프로그램을 별도로 설치해야 합니다.

만약 패키지 매니저로 Yarn을 사용 중이시라면 npm run dev를 yarn dev로, pnpm을 사용 중이시라면 pnpm dev로 수정해주시면 됩니다.

위에 작성한 코드 중 "Next.js: debug full stack" 구성을 한번 자세히 볼까요? 여기서 serverReadyAction.action 옵션은 서버 구동이 완료되었을 때 '어떤 브라우저를 열 것인지'를 지정합니다. 기본적으로 debugWithEdge로 되어 있어서 Edge 브라우저를 띄우게 되는데요, 만약 여러분이 Chrome 브라우저를 주로 쓰신다면 이 값을 debugWithChrome으로 변경해 주시면 됩니다. (저도 실무에서는 보통 Chrome을 쓰기 때문에 꼭 이 부분을 변경해서 사용합니다!)

그리고 애플리케이션이 시작되는 포트 번호를 3000번이 아닌 다른 포트로 변경해서 사용하는 경우, http://localhost:3000 부분의 3000을 여러분이 실제 사용 중인 포트 번호로 꼭 바꿔주셔야 해요.

만약 Next.js를 프로젝트 최상단(root) 폴더가 아닌 다른 하위 디렉토리에서 실행하는 경우 (예를 들어, Turborepo 같은 모노레포 구조를 사용할 때)에는 서버 측 및 풀스택 디버깅 작업 설정에 cwd(현재 작업 디렉토리)를 명시적으로 추가해야 합니다. 예를 들면 "cwd": "${workspaceFolder}/apps/web" 이렇게 적어주시면 되죠.

자, 이제 설정이 끝났습니다! VS Code의 Debug 패널(Windows/Linux에서는 Ctrl+Shift+D, macOS에서는 ⇧+⌘+D)로 이동해서 원하는 디버그 구성을 선택하세요. 그리고 F5 키를 누르거나 Command Palette(명령 팔레트)에서 Debug: Start Debugging을 선택하여 디버깅 세션을 본격적으로 시작해 보세요!

Jetbrains WebStorm에서 디버거 사용하기

혹시 VS Code 대신 WebStorm을 사용하시는 분들도 계시죠?
WebStorm에서는 화면 상단에 런타임 구성(runtime configuration)이 나열된 드롭다운 메뉴를 클릭하고 Edit Configurations...를 클릭하세요.
그리고 URL을 http://localhost:3000으로 설정하여 새로운 JavaScript Debug 구성을 하나 만듭니다. 여기서 사용할 브라우저를 선택하거나 프로젝트 파일로 설정값을 저장하는 등 입맛에 맞게 커스터마이징을 한 뒤 OK를 눌러 저장합니다.
이제 이 디버그 구성을 실행하면, 설정해 둔 브라우저가 짠! 하고 자동으로 열리게 됩니다. 이 시점이 되면 백그라운드에서는 NextJS Node 애플리케이션과 클라이언트 브라우저 애플리케이션, 총 2개의 애플리케이션이 디버그 모드로 동작하게 됩니다.

브라우저 개발자 도구(DevTools)로 디버깅하기

에디터뿐만 아니라, 우리에게 친숙한 크롬이나 파이어폭스의 개발자 도구를 활용해서도 훌륭한 디버깅이 가능합니다. 클라이언트 측 코드와 서버 측 코드를 디버깅하는 방법이 조금 다르니 나누어서 설명해 드릴게요.

클라이언트 측 (Client-side) 코드

우선 평소 개발할 때처럼 터미널에 next dev, npm run dev, 혹은 yarn dev를 입력해서 개발 서버를 켜주세요. 서버가 켜지면 즐겨 쓰는 브라우저를 열고 http://localhost:3000(또는 여러분이 설정한 URL)으로 접속합니다.

Chrome(크롬)을 사용한다면:

  • 크롬 개발자 도구를 엽니다. 단축키는 Windows/Linux: Ctrl+Shift+J, macOS: ⌥+⌘+I 입니다.
  • 상단의 여러 탭 중 Sources 탭으로 이동하세요.

Firefox(파이어폭스)를 사용한다면:

  • 파이어폭스 개발자 도구를 엽니다. 단축키는 Windows/Linux: Ctrl+Shift+I, macOS: ⌥+⌘+I 입니다.
  • 상단의 Debugger 탭으로 이동하세요.

두 브라우저 모두에서, 코드 상에 debugger라는 키워드(statement)를 적어두면 브라우저가 코드를 읽다가 그 지점에서 실행을 일시 정지(pause)시킵니다. 그리고 해당 파일이 디버그 영역에 바로 나타나게 되죠.
굳이 debugger를 직접 타이핑하지 않고 브라우저 안에서 파일을 찾아 마우스 클릭으로 중단점(breakpoint)을 설정할 수도 있습니다.

  • Chrome 환경: Windows/Linux에서는 Ctrl+P, macOS에서는 ⌘+P를 누르고 파일명을 검색하세요.
  • Firefox 환경: Windows/Linux에서는 Ctrl+P, macOS에서는 ⌘+P를 누르거나, 개발자 도구 왼쪽 패널에 있는 파일 트리를 탐색하면 됩니다.

💡 강사의 팁: 브라우저에서 소스 파일을 검색할 때, 원본 파일의 경로는 보통 webpack://_N_E/./로 시작한다는 점을 기억해 두시면 엉뚱한 컴파일 코드를 열어보는 실수를 줄일 수 있습니다!

React Developer Tools (React 개발자 도구)

단순한 자바스크립트 코드 흐름뿐만 아니라, React의 상태(state)나 컴포넌트 구조를 디버깅하고 싶다면 React Developer Tools 브라우저 확장 프로그램 설치는 선택이 아닌 필수입니다! 이 도구는 다음과 같은 강력한 기능들을 제공합니다:

  • React 컴포넌트 검사: 화면의 UI가 어떤 컴포넌트들로 조립되어 있는지 트리 구조로 훤히 볼 수 있습니다.
  • props와 state 수정: 코드를 매번 고치고 새로고침 할 필요 없이, 개발자 도구 화면에서 직접 상태값을 바꿔가며 UI 변화를 즉각적으로 테스트할 수 있어요.
  • 성능 문제 파악: Profiler 기능을 이용해 불필요하게 렌더링(리렌더링)되는 범인을 찾아내 성능을 최적화할 수 있습니다.

서버 측 (Server-side) 코드

Next.js의 매력은 서버 컴포넌트(Server Components)와 API 라우트 같은 서버 측 코드를 쉽게 짤 수 있다는 것이죠. 하지만 브라우저 개발자 도구는 기본적으로 브라우저(클라이언트) 환경을 위해 만들어졌기 때문에, 서버 측 Node.js 환경에서 도는 코드를 검사하려면 Next.js 서버를 띄울 때 --inspect라는 특수한 플래그를 넘겨주어야 합니다.

자신이 사용하는 패키지 매니저에 맞게 아래 명령어를 터미널에 입력해 보세요.

pnpm dev --inspect
npm run dev -- --inspect
yarn dev --inspect
bun run dev --inspect

이렇게 하면 --inspect 플래그의 값이 바탕에 있는 Node.js 프로세스로 전달됩니다. 더 복잡한 고급 설정이나 원리가 궁금하시다면 Node.js 공식 문서의 --inspect 가이드를 확인해 보시면 좋습니다.

알아두면 유용한 팁 (Good to know): 만약 애플리케이션을 Docker 컨테이너 내부에서 실행하는 경우 등 localhost 외부에서 원격으로 디버깅 접근을 허용해야 할 때는 --inspect=0.0.0.0 플래그를 사용하세요. (실무에서 도커를 사용할 때 정말 자주 쓰이는 꿀팁입니다!)

--inspect 플래그를 붙여서 Next.js 개발 서버를 실행하면 터미널 창에 대략 아래와 같은 로그가 찍힐 거예요. Debugger listening on ws://... 이 부분이 중요합니다.

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: [https://nodejs.org/en/docs/inspector](https://nodejs.org/en/docs/inspector)
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

이제 브라우저를 켜서 이 서버 디버거와 연결해 보겠습니다.

Chrome(크롬)의 경우:
1. 브라우저에서 새 탭을 열고 주소창에 chrome://inspect라고 입력 후 접속합니다.
2. 페이지 하단의 Remote Target 섹션에서 내 Next.js 애플리케이션을 찾습니다.
3. 그 아래에 있는 파란색 글씨인 inspect를 클릭하면 별도의 개발자 도구 창이 짠 하고 열립니다.
4. Sources 탭으로 이동해서 서버 측 코드를 확인하세요.

Firefox(파이어폭스)의 경우:
1. 브라우저에서 새 탭을 열고 about:debugging에 접속합니다.
2. 화면 왼쪽 사이드바에서 This Firefox를 클릭합니다.
3. Remote Targets 항목 아래에서 실행 중인 Next.js 애플리케이션을 찾습니다.
4. Inspect 버튼을 클릭하여 디버거를 엽니다.
5. Debugger 탭으로 이동하세요.

서버 측 코드를 디버깅하는 방법도 클라이언트 측과 거의 똑같습니다. 단, 파일 검색(Ctrl+P/⌘+P)을 할 때 주의할 점은 서버 소스 파일의 경로가 webpack://{application-name}/./로 시작한다는 것입니다. (여기서 {application-name} 부분은 여러분의 프로젝트 package.json 파일에 적어둔 앱 이름으로 바뀌어서 보일 거예요.)

만약 코드가 실행되자마자 첫 줄에서 멈춰있게 만들고 싶다면(--inspect-brk), 이 플래그들을 직접 붙이는 대신 환경변수인 NODE_OPTIONS를 지정해야 합니다. 예를 들면 NODE_OPTIONS=--inspect-brk next dev 이런 식으로 실행하는 거죠.

브라우저 개발자 도구로 서버 에러 검사하기

가끔 화면에 시뻘건 에러 오버레이 창이 뜨면서 죽어버릴 때가 있죠? 에러가 발생했을 때 소스 코드를 바로 확인하고 검사할 수 있다면 에러의 근본적인 원인을 추적하는 데 엄청난 도움이 됩니다.

Next.js 최신 버전에서는 브라우저 화면을 덮는 에러 오버레이 화면의 우측 상단(Next.js 버전 표시 바로 아래)에 작은 Node.js 아이콘을 표시해 줍니다. 이 아이콘을 마우스로 클릭하면, 내 서버를 디버깅할 수 있는 개발자 도구 URL이 클립보드에 자동으로 복사됩니다. 이제 브라우저 새 탭을 열고 복사한 URL을 주소창에 붙여넣기만 하면, 즉시 Next.js 서버 프로세스를 검사할 수 있는 환경이 열립니다. (에러 났을 때 정말 직관적이고 편한 기능이니 꼭 한 번 클릭해 보세요!)

Windows(윈도우) 환경에서의 디버깅 관련 주의사항

윈도우 운영체제를 사용 중이신가요? 그렇다면 여러분의 컴퓨터에서 Windows Defender(윈도우 디펜더) 백신 프로그램이 비활성화되어 있는지, 혹은 예외 처리가 되어 있는지 확인해 볼 필요가 있습니다.
이 외부 보안 서비스는 윈도우에서 '읽히는 모든 파일'을 실시간으로 감시하고 검사합니다. 이 때문에 코드를 수정하고 저장할 때마다 변경 사항을 즉시 반영해 주는 next dev의 Fast Refresh(빠른 새로고침) 시간이 극단적으로 느려지는 현상이 빈번하게 보고되고 있습니다.
이건 Next.js 자체의 버그나 문제는 아니지만, Next.js 개발 생산성에 꽤 큰 영향을 미치는 널리 알려진 이슈입니다.

💡 강사의 팁: 백신을 완전히 끄는 것은 보안상 위험할 수 있으니, 윈도우 보안 설정에서 여러분의 '개발 프로젝트 폴더'만 검사 [예외 항목(제외)]으로 등록해 두는 것을 강력히 추천해 드립니다. 설정하고 나면 파일 저장 후 브라우저가 새로고침 되는 체감 속도가 확연하게 달라지는 걸 느끼실 수 있을 거예요!

더 많은 정보 (추가 학습 자료)

JavaScript 디버거를 다루는 방법에 대해 더 깊이 공부하고 싶으신가요? 그렇다면 아래의 훌륭한 공식 문서들을 참고해 보시는 걸 적극 권장합니다.

Next.js 공식 문서의 전체적인 흐름을 시맨틱(의미론적) 개요로 확인하고 싶으시다면 사이트맵(/docs/sitemap.md)을 참조해 주세요.

또한, 사용 가능한 모든 문서의 전체 인덱스(목록)를 보시려면 LLMs.txt 파일(/docs/llms.txt)을 참조하시기 바랍니다.

여러분, 디버깅은 처음엔 낯설고 복잡해 보이지만 손에 익으면 개발 속도를 몇 배는 올려주는 마법 같은 도구입니다. 오늘 배운 내용을 프로젝트에 바로 적용해 보시길 바랄게요. 파이팅입니다!

profile
김동현
프론트에_가까운_풀스택_개발자
이전 포스트

How to think about data security in Next.js

다음 포스트

How to preview content with Draft Mode in Next.js

0개의 댓글