Блог// ИИ

Ошибка window is not defined в Next.js: способы решения

Разбор причин ошибки window is not defined в Next. js и React. Эффективные методы изоляции кода браузера, динамический импорт и условный рендеринг.

07-11-2026 · 5 мин чтения
Ошибка window is not defined в Next.js: способы решения

Ошибка «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.

Пошаговый алгоритм безопасного чтения параметров браузера:

  1. Объявите состояние компонента с дефолтным значением (например, null или базовое число).
  1. Поместите вызов window или localStorage внутри функции обратного вызова useEffect.
  1. Обновите состояние компонента через вызов функции сетера.

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.

Чем можем помочь
Интернет-магазиныМаркетингИИ-роботыСвязаться
← Все статьи