🪲 Next.js 디버깅 가이드

🪲 Next.js 디버깅 가이드

Next.js 애플리케이션을 개발하면서 발생하는 다양한 문제를 효과적으로 해결하기 위해 디버깅 전략을 정리했습니다.
React 특성상 클라이언트와 서버 사이에서 발생하는 이슈를 모두 포괄하여 다룹니다.

---

✅ 1. 기본 디버깅 설정

로그를 활용한 디버깅

Next.js에서는 서버와 클라이언트 로그를 구분하여 출력할 수 있습니다.

// 클라이언트 로그
console.log("클라이언트 측 로그");

// 서버 로그
if (typeof window === "undefined") {
  console.log("서버 측 로그");
}

환경 변수 설정

디버깅 모드를 활성화하려면 .env 파일에 다음 변수를 추가합니다.

NODE_ENV=development
NEXT_PUBLIC_DEBUG=true

개발 환경에서 디버그 정보를 추가로 출력할 때 유용합니다.

---

✅ 2. Next.js 디버깅 도구

Chrome DevTools

• Console: 클라이언트 측 오류 확인
• Network: API 호출 상태 점검
• Performance: 페이지 로딩 속도 확인
• Application: 로컬 스토리지, 세션 관리 확인

VS Code 디버거

VS Code의 Launch Configuration을 활용하여 디버깅 세션을 설정합니다.

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js Debug",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "args": ["dev"],
      "cwd": "${workspaceFolder}",
      "protocol": "inspector",
      "runtimeArgs": ["--inspect"],
      "port": 9229
    }
  ]
}

VS Code에서 F5를 눌러 디버깅을 시작할 수 있습니다.

---

✅ 3. 클라이언트 사이드 디버깅

반응형

React Developer Tools

• Component Tree: 현재 렌더링 중인 컴포넌트 구조 확인
• Props/State: 각 컴포넌트의 상태와 속성 확인
• Hooks: useState, useEffect 등 상태 변화 추적

Error Boundary 활용

예상치 못한 오류로 인해 애플리케이션이 중단되지 않도록 에러 경계를 추가합니다.

// app/ErrorBoundary.tsx
import React from "react";

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    console.error("Error 발생:", error, info);
  }

  render() {
    if (this.state.hasError) {
      return <h1>에러가 발생했습니다.</h1>;
    }

    return this.props.children;
  }
}

export default ErrorBoundary;

---

✅ 4. 서버 사이드 디버깅

서버 로그 활용

Next.js 서버 로그는 터미널에 출력됩니다.

export async function getServerSideProps() {
  console.log("서버에서 데이터 가져오는 중...");
  return { props: {} };
}

환경 변수 확인

console.log("환경 변수:", process.env.NEXT_PUBLIC_API_URL);

디버그 모드 활성화

개발 모드에서 서버를 디버그 모드로 실행합니다.

NODE_OPTIONS='--inspect' npm run dev

디버거가 활성화되면 VS Code에서 연결하여 디버깅할 수 있습니다.

---

✅ 5. 성능 모니터링

Web Vitals 활용

페이지 성능을 분석하여 성능 저하 원인을 파악합니다.

'use client';
import { useReportWebVitals } from 'next/web-vitals';

export default function WebVitalsLogger() {
  useReportWebVitals((metric) => {
    console.log(metric);
  });
  return null;
}

Lighthouse 분석

• 성능 지표: 페이지 로딩 속도, 인터랙티브성 평가
• SEO 체크: 메타 태그 및 접근성 확인
• 최적화 제안: 이미지 압축, 코드 스플리팅 등

---

✅ 6. 런타임 오류 디버깅

Sentry를 사용하여 오류 모니터링

Sentry는 Next.js 프로젝트에서 발생하는 오류를 모니터링하고 보고할 수 있습니다.

설치

npm install @sentry/nextjs

설정

// sentry.client.config.js
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

에러 발생 시 Sentry 대시보드에서 실시간으로 확인할 수 있습니다.

---

✅ 7. 코드 품질 검증

ESLint와 Prettier 설정

코딩 표준을 준수하여 디버깅 시간을 줄입니다.

npm install eslint prettier eslint-plugin-react

설정 파일

// .eslintrc.json
{
  "extends": ["next", "prettier"],
  "plugins": ["react"]
}

스크립트 추가

"scripts": {
  "lint": "eslint . --ext .js,.jsx,.ts,.tsx"
}

---

✅ 요약

디버깅 도구 주요 기능 활용 시점

VS Code 디버거	서버 디버깅	코드 오류 및 변수 확인
Chrome DevTools	클라이언트 디버깅	상태 관리 및 성능 측정
React Developer Tools	상태, props, hooks 모니터링	컴포넌트 트리 디버깅
Error Boundary	예외 처리 및 오류 복구	클라이언트 오류 방지
Sentry	런타임 오류 모니터링	서버 및 클라이언트 오류 추적
Web Vitals	성능 데이터 수집	페이지 성능 최적화

---

 

Next.js, 디버깅, VS Code, Chrome DevTools, React Developer Tools, Sentry, Web Vitals, 성능 모니터링, 런타임 오류, 코드 품질, SEO 최적화