Next.js window is not defined 오류 해결: 브라우저 API를 안전하게 쓰기

• 증상부터 정확히 보기
• 왜 이런 문제가 생기는지
• 실제 코드에서 고치는 방법
• 수정 후 확인할 체크리스트
• 정리

증상부터 정확히 보기

Next.js window is not defined 오류를 만났을 때 먼저 볼 것은 에러 문구 자체보다 문제가 발생한 위치입니다. 같은 증상처럼 보여도 설정 파일에서 생긴 문제인지, 렌더링 시점 문제인지, 데이터나 상태를 바꾸는 방식 문제인지에 따라 해결 방법이 달라집니다.

입문 단계에서는 문제를 빨리 없애려고 가장 강한 해결책부터 붙이기 쉽습니다. 하지만 그렇게 처리하면 다음 화면에서 비슷한 문제가 반복됩니다. 작은 재현 코드로 줄이고, 어떤 값이 어느 시점에 바뀌는지 확인하는 편이 더 안전합니다.

왜 이런 문제가 생기는지

이 문제의 중심에는 브라우저 전용 객체를 서버 실행 시점에 사용해 발생하는 오류가 있습니다. window, document, localStorage, 브라우저 크기 같은 값은 서버 환경에 존재하지 않습니다. 따라서 모듈 최상단이나 서버 컴포넌트 렌더링 중에 이런 값을 바로 읽으면 Next.js가 HTML을 만들거나 빌드하는 과정에서 오류가 날 수 있습니다.

특히 Next 작업에서는 설정, 실행 환경, 상태 참조, 렌더링 순서가 함께 영향을 줍니다. 그래서 “왜 안 되지?”에서 멈추지 말고 어떤 조건에서 재현되는지, 새로고침 후에도 같은지, 빌드 환경에서도 같은지 나눠서 보는 것이 좋습니다.

실제 코드에서 고치는 방법

수정은 문제를 가장 작게 재현한 뒤 적용하는 것이 좋습니다. 아래 예시는 실제 프로젝트 코드 전체가 아니라, 확인해야 할 핵심만 남긴 형태입니다.

'use client';

import { useEffect, useState } from 'react'; function WidthLabel() { const [width, setWidth] = useState(null); useEffect(() => { setWidth(window.innerWidth); }, []); return <p>{width ? `${width}px` : '확인 중'}</p>;
}

코드를 바꿀 때는 결과만 확인하지 말고 “왜 이 방식이면 문제가 사라지는지”를 같이 확인해야 합니다. 컴포넌트가 사용자 이벤트, effect, 브라우저 상태를 사용한다면 'use client' 경계가 필요합니다. 단순히 렌더링 이후에 브라우저 값을 읽으면 되는 경우에는 useEffect 안에서 접근합니다. 외부 라이브러리 자체가 import 시점에 window를 요구한다면 해당 컴포넌트를 클라이언트 컴포넌트로 분리하고 dynamic(() => import(...), { ssr: false })를 검토합니다.

수정 후 확인할 체크리스트

수정 후에는 개발 서버에서만 확인하지 말고 새로고침, 빌드, 실제 데이터 조건을 함께 봅니다. 조건이 하나만 달라져도 문제가 다시 보일 수 있기 때문입니다.

체크할 순서는 간단합니다. 먼저 재현 조건이 사라졌는지 확인하고, 그 다음 같은 패턴이 다른 파일에 남아 있는지 봅니다. 마지막으로 임시 회피 코드가 남아 있지 않은지 정리합니다.

마무리 점검

Next.js window is not defined 오류 해결은 한 가지 정답 코드보다 원인을 좁히는 순서가 더 중요합니다. 증상, 실행 시점, 클라이언트 컴포넌트 경계, 브라우저 전용 라이브러리 여부를 나눠서 보면 불필요한 수정이 줄고, 다음 문제를 만났을 때도 확인할 지점이 분명해집니다.

참고 기준은 Next.js 공식 문서의 Server and Client Components, Lazy Loading, Rendering components only in the browser, Prerender Error를 함께 확인하면 됩니다.