Next.js берёт старые переменные: сборка или запуск

·27 октября 2026 г.· 7 мин чтения

Сколько будет стоить ваш проект?Рассчитать стоимость

Если Next.js после смены переменных показывает старое значение, сначала установите, где оно читается: при сборке, в запущенном серверном процессе или в браузере. Публичная переменная с префиксом NEXT_PUBLIC_, подставленная в клиентский код при сборке, не изменится от одного перезапуска готового приложения. Диагностируйте путь на безвредной тестовой метке, а не публикуйте содержимое конфигурации.

Уточните, что именно осталось старым

Одинаковая надпись на странице может появиться разными путями. Она могла попасть в готовый JavaScript, сформироваться при подготовке страницы или прийти в ответе сервера. Пока путь неизвестен, очистка браузера и повторный запуск процесса выглядят случайным перебором. Найдите место чтения конкретной переменной и проследите, как результат доходит до интерфейса.

Отдельно проверьте, какой релиз действительно обслуживает запрос. Исправленная конфигурация в панели размещения не доказывает, что пользователь получил нужный артефакт. Если копий приложения несколько, они могут различаться. Для этого полезны самостоятельные безопасные метки релиза и конфигурации, не содержащие паролей, адресов закрытых ресурсов или иных секретов.

Клиентская подстановка происходит до открытия страницы

В руководстве Next.js для App Router описана подстановка публичных переменных в JavaScript во время next build. Значение становится частью собранного кода. Поэтому один и тот же готовый образ, перенесённый в другую среду, сохраняет такие значения, даже если при его запуске заданы другие.

В документации также оговорено, что динамическое обращение к переменной по имени не подставляется так же, как прямое обращение. Это не способ спрятать секрет в браузере и не универсальное решение для чтения окружения на клиенте. Сначала выберите, должно ли значение вообще быть публичным, затем реализуйте согласованный способ его доставки.

Карта мест чтения

Таблица помогает выбрать следующую проверку. Серверное значение не всегда означает чтение при каждом запросе: оно может участвовать в подготовке статической страницы. Момент выполнения нужно подтвердить по конкретному коду и режиму, а не определить по названию файла.

Где используется значение	Когда оно влияет на результат	Что проверить	Как подтвердить безопасно	Чего проверка не доказывает
Прямое обращение к NEXT_PUBLIC_ в клиентском коде	При сборке соответствующего кода	Окружение сборщика и идентичность выданного артефакта	Публичная учебная метка в новом артефакте	Перезапуск сервера сам изменил браузерную подстановку
Серверный код при динамической обработке	При фактическом выполнении серверного участка	Окружение обслуживающего процесса и режим чтения	Предусмотренный тестовый ответ с не секретной меткой	Все другие участки тоже читают конфигурацию на запросе
Подготовленная статическая страница	При её генерации по правилам проекта	Стадию генерации и полученный результат	Сопоставление метки страницы с ожидаемым выпуском	Обычное обновление вкладки заново выполнило серверный код
Публичная конфигурация, которую отдаёт свой сервер	При обработке выбранного запроса и по правилам кеширования	Состав разрешённых полей и актуальность ответа	Проверка конкретной публичной метки	Можно отдавать в этом ответе всё окружение

Проверьте источник значения до пересборки

В руководстве для Pages Router указан порядок поиска переменных: существующее окружение процесса проверяется раньше файлов .env. Следом учитываются файлы, зависящие от NODE_ENV, с отдельным правилом для .env.local в тестовой среде. Поэтому исправленный общий файл может не оказаться фактическим источником нужного значения.

Составьте небольшую карту: кто задаёт эту переменную сборщику, кто — запускаемому процессу, какие файлы участвуют и какой режим выбран. В отчёте достаточно имени переменной, типа источника и результата сравнения. Не вставляйте значения секретов в тикет или журнал. Проверять полный дамп окружения ради одной надписи на странице не требуется.

Учтите и размещение файлов: документация Next.js отдельно указывает, что при использовании каталога src файлы .env остаются в корне проекта. Но не переставляйте файлы на рабочем сервере по общей статье. Сначала проверьте структуру конкретного проекта и то, каким способом платформа передаёт настройки.

Испытание с метками вместо реальных ключей

Для учебного прогона выберите две различимые строки, например release-a и release-b. Они не должны кодировать секрет или персональные данные. Используйте специально предусмотренную публичную метку и отдельный тестовый путь серверного чтения. Не переименовывайте рабочий секрет так, чтобы он стал доступен браузеру.

Найдите использование проблемной переменной. Зафиксируйте, относится ли наблюдаемый результат к клиентскому коду, генерации страницы или динамической серверной обработке.
В согласованной тестовой среде соберите приложение с публичной меткой release-a. Убедитесь, что именно этот артефакт получает браузер.
Измените только окружение запуска на release-b, сохранив готовую сборку. Для встроенного публичного значения ожидается прежняя метка; серверный тест проверяется отдельно по своему режиму.
Подготовьте новую сборку с публичной меткой release-b и подтвердите, что выдаётся уже она. Не сравнивайте результаты, если запросы попадают в разные неизвестные копии.
Если значение всё ещё неожиданное, сверяйте источник окружения, выбранный режим и маршрут выдачи. Проверяйте кеш конкретного результата после установления его происхождения.
Удалите временную диагностику, если она не является согласованной функцией. Зафиксируйте, на каком этапе должна задаваться конфигурация при следующем выпуске.

Когда значение действительно нужно менять без новой сборки

Если браузеру необходимо получать настройку при работе приложения, предусмотрите отдельный публичный контракт: только разрешённые поля, понятный момент обновления и правила кеширования. В руководстве Pages Router такой собственный API приведён как путь доставки runtime-значений клиенту. Это проектное изменение, а не повод открывать весь объект окружения.

Для серверного чтения в App Router документация описывает динамическое выполнение; у Pages Router показан свой подход к данным на запросе. Применяйте вариант, соответствующий используемому маршрутизатору и версии проекта. Не переносите отдельный пример API в другой режим без проверки. Если страница заранее сгенерирована, расположение кода на сервере само по себе не делает значение динамическим.

Исправление должно пережить следующий выпуск

После диагностики закрепите правило в процедуре выпуска: какие настройки задаются до сборки, какие при запуске, а какие разрешено отдавать клиенту. Привяжите проверку к нужному артефакту и предусмотрите безопасный способ узнать его метку. Тогда повтор проблемы можно будет локализовать без перебора перезапусков и выгрузки чувствительной конфигурации.

Жизненный цикл конфигурации стоит согласовать при разработке веб-приложения, размещение и обновления — в рамках поддержки сервера, публичность настроек — при аудите SaaS. Готовый результат — понятное место изменения и воспроизводимая проверка, что пользователь получает ожидаемое значение в нужном режиме.

Вопросы и ответы

Почему NEXT_PUBLIC_ environment variables не меняются после запуска?

При прямой подстановке в клиентский код они фиксируются во время сборки. Изменение окружения запуска готового артефакта само по себе не переписывает этот JavaScript.

Как проверить Next.js environment variables runtime?

Сначала определите участок серверного кода, который действительно выполняется при обработке запроса. Для теста используйте безопасную метку и отдельно подтвердите окружение процесса и режим страницы, не выводя секреты.

Где искать причину Next.js env variables undefined?

Проверьте имя, фактический источник окружения, расположение файлов и момент чтения. Отсутствующее значение и старое встроенное значение — разные симптомы, а добавление публичного префикса к секрету не является безопасным исправлением.

Нужна помощь с проектом?

Обсудим задачу и предложим решение — от сайта до SaaS и защиты.

Связаться