icon
18장 : 문제 해결 및 디버깅

브라우저 개발자 도구 활용

웹 애플리케이션 개발에서 브라우저 개발자 도구(Browser Developer Tools) 는 코드 디버깅, 성능 분석, UI/UX 문제 해결 등 다양한 문제를 진단하고 해결하는 데 필수적인 도구입니다. 복잡한 Next.js 애플리케이션을 개발할 때, 개발자 도구를 능숙하게 활용하는 것은 문제 해결 시간을 단축하고 전반적인 개발 효율성을 크게 향상시킬 수 있습니다.

이 절에서는 Chrome 개발자 도구를 중심으로 주요 패널들의 기능과 Next.js 애플리케이션 디버깅 시 활용 팁을 상세히 살펴보겠습니다.


개발자 도구 열기

대부분의 최신 웹 브라우저(Chrome, Firefox, Edge, Safari 등)는 내장 개발자 도구를 제공합니다. Chrome에서 개발자 도구를 여는 가장 일반적인 방법은 다음과 같습니다:

  • 마우스 오른쪽 클릭: 웹 페이지에서 마우스 오른쪽 버튼을 클릭하고 "검사(Inspect)" 를 선택합니다.
  • 단축키
    • Windows/Linux: Ctrl + Shift + I 또는 F12
    • macOS: Cmd + Option + I

개발자 도구는 일반적으로 브라우저 창 하단 또는 측면에 도킹된 형태로 나타납니다.


주요 패널 활용법

Chrome 개발자 도구는 다양한 기능을 수행하는 여러 패널로 구성되어 있습니다. Next.js 개발 시 가장 자주 사용되는 패널들을 중심으로 살펴보겠습니다.

Elements (요소) 패널

용도: 웹 페이지의 HTML 및 CSS 구조를 실시간으로 확인하고 수정할 수 있습니다. 렌더링된 DOM 트리를 탐색하고, 각 요소에 적용된 스타일을 검사하며, 스타일을 즉시 변경하여 시각적인 효과를 확인할 수 있습니다.

  • HTML 구조 탐색: 왼쪽의 DOM 트리에서 요소를 클릭하거나, 페이지에서 "요소 선택" 도구(마우스 포인터 아이콘)를 사용하여 특정 요소를 선택할 수 있습니다.
  • Styles(스타일) 탭: 선택된 요소에 적용된 모든 CSS 규칙을 표시합니다.
    • 각 규칙의 출처(파일, 줄 번호)를 확인할 수 있습니다.
    • 속성 값을 클릭하여 즉시 수정하고 페이지에 반영되는 것을 확인할 수 있습니다.
    • 새로운 CSS 규칙을 추가하거나, 기존 규칙을 비활성화/활성화할 수 있습니다.
  • Computed(계산됨) 탭: 브라우저가 최종적으로 계산한 요소의 모든 스타일 속성(상속된 속성 포함)을 보여줍니다.
  • Layout 탭: 요소의 박스 모델(margin, border, padding, content)을 시각적으로 보여주어 레이아웃 문제를 진단하는 데 유용합니다.
  • Event Listeners(이벤트 리스너) 탭: 선택된 요소에 연결된 모든 JavaScript 이벤트 리스너를 표시하고, 소스 코드로 이동할 수 있습니다.
  • 활용 팁 (Next.js)
    • CSS 문제 디버깅: Tailwind CSS나 CSS Modules를 사용할 때 스타일이 예상대로 적용되지 않을 경우, Elements 패널에서 실제 적용된 클래스와 스타일을 확인하여 문제의 원인을 파악합니다.
    • Hydration 오류 진단: 서버에서 렌더링된 HTML과 클라이언트에서 하이드레이션(hydration)된 HTML이 일치하지 않을 때 발생하는 오류(Hydration failed...)의 경우, Elements 패널을 통해 서버에서 받은 초기 HTML과 클라이언트에서 렌더링된 HTML의 차이점을 시각적으로 비교해 볼 수 있습니다.

Console (콘솔) 패널

용도: JavaScript 코드 실행 중 발생하는 오류 메시지, 경고, 디버그 메시지(console.log, console.error 등)를 표시합니다. JavaScript 코드를 직접 실행하여 테스트하거나 변수 값을 확인할 수도 있습니다.

  • 오류 및 경고 메시지: 클라이언트 측에서 발생하는 모든 JavaScript 오류와 경고를 실시간으로 표시합니다. 클릭하면 해당 코드의 소스 위치로 이동할 수 있습니다.
  • console.log() 출력: 개발자가 코드에 삽입한 모든 console.log, console.info, console.warn, console.error 메시지가 여기에 나타납니다.
  • JavaScript 코드 실행: 콘솔 하단에 명령 프롬프트가 있어 JavaScript 코드를 직접 입력하고 실행하여 변수 값을 확인하거나 함수를 호출해 볼 수 있습니다.
  • 활용 팁 (Next.js)
    • 클라이언트 측 오류 추적: 클라이언트 컴포넌트에서 발생하는 JavaScript 오류나 예상치 못한 동작을 디버깅할 때 필수적입니다.
    • Server Component/API Route 로그 확인: console.log가 서버 컴포넌트나 API Routes에 있다면, 이는 터미널(개발 환경)이나 Vercel 대시보드의 Logs 탭에서 확인해야 합니다. 브라우저 콘솔에서는 클라이언트 측 로그만 볼 수 있습니다.
    • 상태 값 확인: React 컴포넌트의 상태(state)나 props 값을 console.log로 출력하여 흐름을 추적합니다.

Sources (소스) 패널

용도: 웹 페이지를 구성하는 JavaScript, CSS, HTML 파일을 확인하고, JavaScript 코드에 브레이크포인트(Breakpoint) 를 설정하여 코드 실행을 일시 중지하고 디버깅할 수 있습니다.

  • 파일 탐색: 왼쪽 탐색기에서 프로젝트의 소스 코드 파일들을 찾을 수 있습니다. Next.js 앱의 경우 .next 폴더 아래에 빌드된 코드와 소스 맵 파일들이 있습니다.
  • 브레이크포인트 설정: JavaScript 코드 라인 번호를 클릭하여 브레이크포인트를 설정합니다. 코드가 해당 지점에 도달하면 실행이 멈추고, 변수 값을 검사하거나 코드를 한 줄씩 실행(Step over, Step into)할 수 있습니다.
  • Scope(스코프) 및 Watch(감시) 영역: 브레이크포인트에서 멈췄을 때, 현재 스코프 내의 모든 변수 값과 미리 설정한 특정 변수 값을 실시간으로 감시할 수 있습니다.
  • Call Stack(호출 스택): 현재 실행 중인 함수의 호출 경로를 보여주어 코드의 실행 흐름을 파악하는 데 도움을 줍니다.
  • 활용 팁 (Next.js)
    • 클라이언트 컴포넌트 디버깅: 클라이언트 컴포넌트 내부의 복잡한 로직이나 이벤트 핸들러에서 문제가 발생했을 때 브레이크포인트를 설정하여 심층적으로 디버깅합니다.
    • Source Map 확인: Next.js는 개발 모드에서 Source Map을 자동으로 생성하여 빌드된 코드에서 원본 TypeScript/JavaScript 코드를 볼 수 있도록 해줍니다. webpack://.next/static/chunks/app/ 등에서 원본 파일을 찾을 수 있습니다.

Network (네트워크) 패널

용도: 웹 페이지 로딩 시 발생하는 모든 네트워크 요청(HTTP/HTTPS)을 기록하고 분석합니다.

  • 요청 목록: 페이지 로딩에 필요한 모든 리소스(HTML, CSS, JS, 이미지, 폰트, API 호출)의 목록이 시간 순서대로 표시됩니다.
  • 상태 코드: 각 요청의 HTTP 상태 코드(200 OK, 404 Not Found, 500 Internal Server Error 등)를 확인할 수 있습니다.
  • 유형 및 크기: 요청된 리소스의 유형(JS, CSS, Img, Fetch/XHR 등)과 파일 크기를 보여줍니다.
  • 시간: 각 리소스의 로딩 시간, 대기 시간(TTFB - Time to First Byte) 등을 상세하게 보여줍니다.
  • Preview/Response 탭: API 요청의 경우, 응답 데이터(JSON, HTML 등)를 미리 보거나 전체 응답 내용을 확인할 수 있습니다.
  • Header(헤더) 탭: 요청 및 응답 헤더 정보를 확인할 수 있습니다. 특히 캐싱 관련 헤더(Cache-Control)를 확인할 때 유용합니다.
  • 활용 팁 (Next.js)
    • API Routes 디버깅: Next.js API Routes나 Server Actions를 통해 데이터를 가져올 때, 네트워크 패널에서 해당 요청의 성공 여부, 응답 데이터, 응답 시간 등을 확인하여 백엔드 문제가 아닌지 파악합니다.
    • 성능 분석: 과도하게 큰 이미지나 JavaScript 파일, 느린 API 응답 등을 식별하여 성능 병목 현상을 찾아냅니다. "Disable cache" 옵션을 사용하여 캐시가 없는 상태에서의 로딩 성능을 측정합니다.
    • 캐싱 확인: Vercel 배포 후 캐싱이 제대로 작동하는지 확인하기 위해 Cache-Control 헤더를 검사합니다.

Application (애플리케이션) 패널

용도: 웹 애플리케이션의 클라이언트 측 저장소(로컬 스토리지, 세션 스토리지, IndexedDB, 쿠키)와 서비스 워커, 캐시 스토리지 등을 관리하고 검사합니다.

  • Local Storage/Session Storage/Cookies: 클라이언트 측에 저장된 데이터를 확인하고 수정하거나 삭제할 수 있습니다. 인증 토큰, 사용자 설정 등 디버깅 시 유용합니다.
  • Cache Storage: 서비스 워커가 캐싱한 리소스 목록을 확인하고 관리할 수 있습니다. PWA 개발 시 유용합니다.
  • 활용 팁 (Next.js)
    • 인증/세션 디버깅: 사용자 인증(NextAuth.js 등) 시 쿠키나 로컬 스토리지에 저장되는 토큰, 세션 ID 등을 확인하여 인증 관련 문제를 진단합니다.
    • 클라이언트 캐싱 문제: PWA 기능이나 Service Worker를 사용할 때, 캐시된 데이터가 예상과 다를 경우 Application 패널을 통해 캐시를 비우거나 내용을 확인할 수 있습니다.

Performance (성능) 패널

용도: 웹 페이지의 런타임 성능을 기록하고 상세하게 분석합니다. 프레임 드롭, 레이아웃 스래싱, 긴 JavaScript 작업 등을 식별하는 데 매우 강력합니다.

  • 기록 및 분석: "기록(Record)" 버튼을 클릭하여 사용자 인터랙션이나 페이지 로딩 과정을 기록하고, 기록이 완료되면 상세한 타임라인 그래프와 요약 정보를 제공합니다.
  • CPU/Network 활동: CPU 사용량, 네트워크 활동, 렌더링 과정 등을 시각적으로 보여줍니다.
  • Flame Chart(불꽃 차트): JavaScript 함수 호출 스택을 시각적으로 표현하여 어떤 함수가 많은 시간을 소비하는지 직관적으로 파악할 수 있습니다.
  • 활용 팁 (Next.js)
    • 리액트 컴포넌트 성능 분석: react-dev-tools와 함께 사용하여 컴포넌트의 렌더링 주기, 리렌더링 원인 등을 분석하여 불필요한 렌더링을 줄일 수 있습니다. (설정에서 React DevTools 프로파일링 옵션 활성화)
    • 애니메이션 성능: 복잡한 애니메이션이나 스크롤 시 버벅거림(jank)이 발생할 때 Performance 패널을 통해 레이아웃 재계산이나 페인트 작업이 과도하게 일어나는지 확인할 수 있습니다.

디버깅 워크플로우 예시 (Next.js)

  1. 문제 인지: 특정 기능이 작동하지 않거나, 페이지 로딩이 느리거나, UI가 깨지는 등 문제를 발견합니다.
  2. 초기 진단 (Console & Network)
    • 먼저 Console 패널을 열어 클라이언트 측 오류 메시지나 경고가 있는지 확인합니다.
    • 다음으로 Network 패널을 열어 API 요청이 성공했는지(200 OK), 느리지는 않은지, 예상한 응답 데이터를 받는지 확인합니다.
    • 만약 서버 측 로그가 필요하다면, 로컬 개발 환경 터미널이나 Vercel 대시보드 Logs 탭을 확인합니다.
  3. UI/CSS 문제 (Elements)
    • UI 레이아웃이 깨지거나 스타일이 적용되지 않는다면 Elements 패널에서 해당 요소를 선택하여 적용된 CSS 규칙을 검사하고, 스타일을 즉시 수정해가며 문제를 진단합니다.
  4. JavaScript 로직 문제 (Sources)
    • JavaScript 로직이나 상태 관리에서 문제가 발생한다면 Sources 패널로 이동합니다.
    • 의심되는 코드 라인에 브레이크포인트를 설정하고, 페이지를 새로고침하거나 해당 기능을 트리거합니다.
    • 코드 실행이 멈추면 ScopeWatch 영역에서 변수 값을 확인하고, Call Stack을 통해 함수 호출 흐름을 파악합니다. Step over, Step into 등의 버튼을 사용하여 코드를 한 줄씩 실행하며 동작을 분석합니다.
  5. 성능 문제 (Performance & Network)
    • 페이지 로딩이 느리거나 인터랙션이 버벅거린다면 Performance 패널에서 기록을 시작하여 병목 현상을 시각적으로 분석합니다.
    • Network 패널에서 큰 리소스나 느린 요청을 다시 한번 확인하고, 필요하다면 next/image, next/script 등으로 최적화를 시도합니다.
  6. 저장소/캐싱 문제 (Application)
    • 로그인 상태가 유지되지 않거나 캐시된 데이터가 잘못될 경우 Application 패널에서 쿠키, 로컬 스토리지, 캐시 스토리지 등을 확인하고 필요에 따라 데이터를 삭제하여 테스트합니다.

브라우저 개발자 도구는 웹 개발자의 가장 강력한 무기 중 하나입니다. 각 패널의 기능을 익히고 다양한 문제 상황에 적용하는 연습을 통해, 어떤 Next.js 프로젝트에서도 효과적으로 문제를 해결하고 애플리케이션의 품질을 높일 수 있을 것입니다.