Ошибка window is not defined в Next.js: способы решения
Разбор причин ошибки window is not defined в Next. js и React. Эффективные методы изоляции кода браузера, динамический импорт и условный рендеринг.
Ошибка «window is not defined» в Next.js и React возникает из-за выполнения браузерного кода на стороне сервера в средах SSR или SSG, где объект window отсутствует. Для решения применяют проверку среды исполнения, хуки жизненного цикла, динамические импорты компонентов без SSR или клиентские директивы.
Причина возникновения сбоя в гибридном рендеринге
В фреймворке Next.js код компонентов по умолчанию исполняется в двух средах: на стороне сервера (Node.js) в процессе серверного рендеринга (SSR) или статической генерации (SSG), и на стороне клиента в браузерном окружении. Глобальный объект window, а также document, localStorage и navigator существуют исключительно в Web API браузера. При попытке сервера отрендерить страницу Node.js встречает обращение к несистематизированному объекту window, что приводит к аварийному завершению процесса с ошибкой ReferenceError: window is not defined.
Качество архитектуры программных систем и обработка исключительных ситуаций регулируются стандартом ГОСТ Р ИСО/МЭК 25010-2015. Для обеспечения отказоустойчивости веб-приложения необходимо четко разграничивать серверную и клиентскую логику на этапе проектирования сборок.
Метод 1. Проверка наличия объекта через typeof window
Самый быстрый способ предотвратить выполнение браузерного кода на сервере — добавить условную проверку типа глобальной переменной перед вызовом браузерных API.
typescript if (typeof window !== 'undefined') { const theme = localStorage.getItem('theme'); console.log('Ширина экрана:', window.innerWidth); }
Этот подход подходит для изолированных функций-хелперов, утилит и сервисных файлов. Однако при работе с компонентами React прямое использование условных конструкций в теле функции может вызывать ошибку несовпадения гидратации (Hydration Mismatch), когда сгенерированный сервером HTML отличается от первичного клиентского дерева.
Метод 2. Изоляция обращения к DOM в хуках useEffect и useLayoutEffect
В React хук useEffect гарантированно выполняется только на стороне клиента после того, как компонент смонтирован в DOM-дерево. Серверный рендерер полностью игнорирует содержимое useEffect.
Пошаговый алгоритм безопасного чтения параметров браузера:
- Объявите состояние компонента с дефолтным значением (например,
nullили базовое число).
- Поместите вызов
windowилиlocalStorageвнутри функции обратного вызоваuseEffect.
- Обновите состояние компонента через вызов функции сетера.
tsx import { useState, useEffect } from 'react';
export default function ScreenWidth { const [width, setWidth] = useState<number | null>(null);
useEffect( => { setWidth(window.innerWidth);
const handleResize = => setWidth(window.innerWidth); window.addEventListener('resize', handleResize); return => window.removeEventListener('resize', handleResize); }, []);
if (width === null) return <div>Загрузка...</div>; return <div>Ширина окна: {width}px</div>; }
Метод 3. Динамический импорт компонентов с отключением SSR
Многие сторонние библиотеки (карт, графиков, WYSIWYG-редакторов) обращаются к window сразу при импорте модуля на верхнем уровне. В таких случаях обычный import ломает серверную сборку.
Для решения проблемы в Next.js используется утилита dynamic из модуля next/dynamic с отключенным рендерингом на сервере:
tsx import dynamic from 'next/dynamic';
const ChartNoSSR = dynamic( => import('../components/InteractiveChart'), { ssr: false } );
export default function Page { return ( <main> <h1>Аналитическая панель</h1> <ChartNoSSR /> </main> ); }
Использование динамических импортов соответствует классификации и принципам модульности интерактивных систем по ГОСТ Р 59277-2020.
Сравнение способов решения ошибки window is not defined в Next.js
| Способ решения | Сфера применения | Влияние на SSR / SEO | Сложность реализации |
|---|---|---|---|
| Проверка typeof window !== 'undefined' | Утилиты, хелперы, синхронные функции | Сохраняет SSR, пропускает код на сервере | Низкая |
| Использование хука useEffect | Компоненты React, подписка на события DOM | Код выполняется строго после гидратации | Низкая |
| next/dynamic с { ssr: false } | Тяжелые UI-модули, карты, графики, редакторы | Исключает компонент из серверного HTML | Средняя |
| Директива 'use client' | Клиентские интерактивные компоненты App Router | Позволяет использовать клиентские хуки | Низкая |
Метод 4. Разделение архитектуры в App Router через директиву use client
В Next.js 13+ (архитектура App Router) все компоненты по умолчанию являются серверными (Server Components). Они выполняются строго на сервере и не имеют доступа к Web API.
Чтобы перевести компонент в разряд клиентских (Client Component), добавьте директиву 'use client' в самую первую строку файла:
tsx 'use client';
import { useEffect } from 'react';
export default function ClientButton { useEffect( => { console.log('Пользовательский агент:', window.navigator.userAgent); }, []);
return <button onClick={ => alert(window.location.href)}>Поделиться</button>; }
Обратите внимание: добавление директивы 'use client' не означает, что компонент рендерится исключительно в браузере. Он всё равно проходит этап предварительного SSR-рендеринга HTML, поэтому прямое обращение к window вне хука useEffect в клиентском компоненте по-прежнему вызовет ошибку.
Типичные ошибки при интеграции сторонних браузерных библиотек
При разработке сложных веб-интерфейсов разработчики часто сталкиваются с сопутствующими проблемами локального окружения и сборки:
- Импорт библиотеки в глобальном файле
_app.tsxилиlayout.tsxбез изоляции.
- Запуск локального сервера разработки на адресе
http://127.0.0.1:3000без проверки ошибок сбора ресурсов в консоли.
- Попытка обращения к
windowвнутри функцийgetServerSidePropsилиgetStaticProps(эти функции исполняются исключительно в среде Node.js).
Если вам требуется качественная веб-разработка, организация устойчивой архитектуры приложений или комплексная цифровая трансформация, обратите внимание на разработку интернет-магазинов и внедрение AI-ассистентов от специалистов на официальном сайте компании.
Часто задаваемые вопросы
Почему ошибка window is not defined происходит при сборке проекта через next build?
Во время выполнения сборки Next.js пререндерит страницы в среде Node.js для генерации статического HTML. Если модуль или библиотека обращается к объекту window на этапе первичной загрузки файла, процесс сборки прерывается из-за отсутствия объектов браузерного окружения в Node.js.
Можно ли использовать window внутри хука useState при инициализации состояния?
Использовать window напрямую в начальном значении useState(window.innerWidth) нельзя, так как этот вызов сработает на сервере. Необходимо передавать базовое значение по умолчанию, а затем обновлять его внутри хука useEffect после вызова маунтинга компонента.
В чем разница между typeof window !== 'undefined' и хуком useEffect для гидратации?
Проверка typeof window позволяет обойти выполнение кода на сервере, но может привести к расхождению сгенерированного HTML и клиентского DOM (hydration mismatch). Использование useEffect гарантирует вызов кода строго после завершения первичной гидратации страницы.
Как правильно подключать сторонние библиотеки вроде Leaflet или Chart.js в Next.js?
Подобные библиотеки запрашивают DOM API сразу при импорте. Их следует подключать через инструмент next/dynamic с отключенным параметром SSR ({ ssr: false }) или выполнять динамический импорт import внутри useEffect.
Материал подготовил: Редакция aiforsale.ru, Эксперт направления.
Эксперт по созданию сайтов, рекламе в интернете и маркетингу с 2012 года. Основатель агентства AIFORSALE.