Next.js 신입 트러블슈팅 기술면접

Hydration 에러는 서버 사이드 렌더링(SSR) 시 생성된 HTML과 클라이언트에서 React가 다시 렌더링한 결과가 일치하지 않을 때 발생합니다. 주요 원인으로는 서버와 클라이언트에서 다른 값을 반환하는 Date.now()나 Math.random() 같은 함수 사용, window나 localStorage 같은 브라우저 전용 API 사용, 조건부 렌더링에서 서버/클라이언트 환경 차이 등이 있습니다. 해결 방법은 useEffect 훅 내부에서 클라이언트 전용 로직을 실행하거나, suppressHydrationWarning 속성을 사용하거나, 서버와 클라이언트에서 동일한 초기값을 사용하도록 수정하는 것입니다. 또한 개발자 도구의 콘솔에서 정확히 어떤 요소가 불일치하는지 확인하여 해당 부분을 수정해야 합니다.

배포 환경에서만 404가 발생하는 경우 가장 흔한 원인은 파일명의 대소문자 문제입니다. Windows나 macOS는 파일명 대소문자를 구분하지 않지만 Linux 기반 서버는 구분하므로, 코드에서 'About.tsx'를 참조하는데 실제 파일명이 'about.tsx'인 경우 배포 시 404가 발생합니다. 또한 pages 폴더 구조가 올바른지, 동적 라우팅을 사용하는 경우 대괄호 파일명이 정확한지 확인해야 합니다. getStaticPaths를 사용하는 동적 페이지에서 fallback 설정이 적절한지도 점검해야 하며, 빌드 로그를 확인하여 해당 페이지가 정상적으로 생성되었는지 검증해야 합니다.

Next.js Image 컴포넌트는 보안과 최적화를 위해 외부 도메인의 이미지를 기본적으로 차단합니다. next.config.js 파일에서 images.domains 또는 images.remotePatterns 설정을 통해 허용할 도메인을 명시해야 합니다. Next.js 12.3 이후 버전에서는 remotePatterns가 권장되며, 프로토콜, 호스트명, 경로 패턴을 더 세밀하게 제어할 수 있습니다. 설정 변경 후에는 개발 서버를 재시작해야 적용되며, 배포 환경에서는 재빌드가 필요합니다. 또한 이미지 src가 올바른 URL 형식인지, width와 height 속성이 제공되었는지도 함께 확인해야 합니다.

이 에러는 API 라우트 핸들러 함수가 클라이언트에게 응답을 보내지 않고 종료될 때 발생합니다. 주요 원인은 res.json()이나 res.send() 같은 응답 메서드를 호출하지 않았거나, 비동기 함수에서 await 키워드를 빼먹어 Promise가 완료되기 전에 함수가 종료되는 경우입니다. 해결 방법은 모든 코드 경로에서 반드시 res.status().json() 등의 응답을 보내도록 하고, async/await을 올바르게 사용하며, try-catch 블록에서 에러 발생 시에도 응답을 보내도록 처리하는 것입니다. 또한 조건문의 모든 분기에서 응답이 전송되는지 확인해야 합니다.

빌드 시에만 발생하는 Module not found 에러는 여러 원인이 있습니다. 첫째, import 경로에서 파일 확장자를 생략했거나 상대 경로가 잘못된 경우입니다. 둘째, 패키지가 devDependencies에만 설치되어 있고 프로덕션 빌드 시 포함되지 않은 경우입니다. 셋째, node_modules 폴더가 .gitignore에 포함되어 배포 환경에서 npm install이 제대로 실행되지 않은 경우입니다. 넷째, 클라이언트 코드에서 Node.js 전용 모듈을 import하려고 시도하는 경우입니다. 해결을 위해서는 에러 메시지에서 정확한 모듈명을 확인하고, package.json의 dependencies를 점검하며, 빌드 환경에서 npm ci 명령으로 깨끗하게 재설치해봐야 합니다.

getServerSideProps의 성능 문제는 외부 API 의존성 때문에 발생합니다. 먼저 콘솔에 API 호출 시작과 종료 시간을 로깅하여 정확한 응답 시간을 측정해야 합니다. try-catch 블록으로 에러를 잡아 로깅하고, API 실패 시에도 페이지가 렌더링되도록 fallback 데이터를 제공해야 합니다. 근본적인 해결책으로는 getStaticProps + revalidate를 사용해 ISR(Incremental Static Regeneration)로 전환하거나, 클라이언트 사이드에서 SWR이나 React Query로 데이터를 가져오는 방법을 고려할 수 있습니다. 또한 외부 API에 타임아웃 설정을 추가하고, 캐싱 전략을 도입하여 반복 호출을 줄여야 합니다.

Next.js에서 환경 변수는 기본적으로 서버 사이드에서만 접근 가능합니다. 클라이언트(브라우저)에서 접근하려면 변수명 앞에 NEXT_PUBLIC_ 접두사를 붙여야 합니다. 예를 들어 NEXT_PUBLIC_API_KEY로 선언하면 브라우저에서 process.env.NEXT_PUBLIC_API_KEY로 접근할 수 있습니다. 단, 이렇게 노출된 환경 변수는 빌드 타임에 번들에 포함되어 클라이언트에 완전히 노출되므로, 민감한 정보(비밀 키, 토큰 등)는 절대 NEXT_PUBLIC_을 붙이면 안 됩니다. 민감한 API 호출은 API Routes를 통해 서버 사이드에서 처리해야 합니다. 환경 변수 변경 후에는 개발 서버를 재시작해야 적용됩니다.

styled-components 같은 CSS-in-JS 라이브러리를 Next.js에서 사용할 때는 서버 사이드 렌더링 설정이 필요합니다. _document.js 파일을 생성하고 ServerStyleSheet을 사용해 서버에서 스타일을 수집하여 초기 HTML에 포함시켜야 합니다. next.config.js에 compiler.styledComponents: true 옵션을 추가하면 Next.js 12 이후 버전에서는 SWC 컴파일러가 자동으로 처리해줍니다. 또한 babel-plugin-styled-components를 설치하고 .babelrc 설정이 필요할 수 있습니다. 깜빡임은 클라이언트에서 스타일이 다시 주입되는 과정에서 발생하므로, 서버와 클라이언트의 스타일 렌더링을 일치시키는 것이 핵심입니다. 최신 프로젝트에서는 Tailwind CSS나 CSS Modules 같은 대안도 고려할 수 있습니다.

Next.js는 기본적으로 페이지 이동 시 스크롤을 최상단으로 이동시키지만, 브라우저 히스토리 이동(뒤로가기/앞으로가기) 시에는 이전 스크롤 위치를 복원합니다. 의도적으로 스크롤을 제어하려면 Link 컴포넌트의 scroll 속성을 사용할 수 있습니다. scroll={false}로 설정하면 자동 스크롤이 비활성화되고, 필요시 useEffect에서 window.scrollTo(0, 0)로 수동 제어할 수 있습니다. 또한 next.config.js의 scrollRestoration 옵션으로 전역 동작을 변경하거나, router.push의 두 번째 인자에 scroll 옵션을 전달할 수도 있습니다. 특정 앵커로 이동하려면 hash를 URL에 포함시키면 됩니다.

개발 서버의 메모리 증가는 Fast Refresh(HMR) 사용 시 자주 발생하는 현상입니다. 주요 원인은 컴포넌트에서 정리되지 않은 이벤트 리스너, setInterval/setTimeout, 구독(subscription) 등이 페이지 수정 시 계속 쌓이는 것입니다. useEffect의 cleanup 함수에서 모든 구독을 해제하고 타이머를 정리해야 합니다. 또한 전역 변수나 모듈 레벨 캐시가 계속 쌓이는지 확인하고, 개발 중에는 주기적으로 서버를 재시작하는 것도 방법입니다. node --max-old-space-size 옵션으로 Node.js 메모리 제한을 늘릴 수 있지만 근본 해결책은 아닙니다. Chrome DevTools의 Memory 프로파일러나 Node.js의 --inspect 옵션으로 메모리 누수를 분석할 수 있습니다.