Гайды19 октября 2026 г.

Как настроить переменные окружения Next.js для продакшена: полное руководство

Пошаговое руководство с примерами и советами по безопасности

06 874 просмотров4 мин

Поделиться:Telegram VK

Введение

Переменные окружения — это ключевой механизм конфигурации приложений, позволяющий хранить чувствительные данные (API-ключи, строки подключения к базам данных) вне исходного кода. В Next.js работа с ними имеет свои особенности: разные файлы для разных окружений, префиксы для клиентских переменных, встраивание на этапе сборки. Если вы готовите приложение к продакшену, важно правильно организовать env-переменные, чтобы избежать утечек секретов и ошибок конфигурации.

В этом руководстве мы разберём, как настроить переменные окружения в Next.js для продакшена: от создания файлов .env до деплоя на сервер и в облачные платформы. Вы узнаете, чем отличаются серверные и клиентские переменные, как избежать типичных ошибок и обеспечить безопасность.

Требования

Установленный Node.js (версия 18 или выше)
Проект на Next.js (версия 12+; примеры актуальны для App Router и Pages Router)
Базовые знания JavaScript и работы с командной строкой
Понимание, что такое переменные окружения

Шаг 1: Понимание типов переменных в Next.js

Next.js поддерживает два типа переменных:

Серверные — доступны только в серверном коде (API routes, getServerSideProps, серверные компоненты). Не попадают в клиентский бандл.
Клиентские — должны иметь префикс NEXT_PUBLIC_. Встраиваются в JavaScript-бандл на этапе сборки и доступны в браузере.

Важно: клиентские переменные не являются секретными, так как видны любому пользователю. Никогда не храните в них пароли и приватные ключи.

Шаг 2: Создание файлов .env для разных окружений

Next.js автоматически загружает переменные из файлов .env в зависимости от окружения:

.env — загружается всегда
.env.local — загружается всегда, кроме тестового окружения; игнорируется git
.env.development — только для development
.env.production — только для production
.env.development.local, .env.production.local — локальные переопределения

Создайте в корне проекта файлы:

# .env (общие переменные)
DATABASE_URL=postgres://user:pass@localhost:5432/mydb

# .env.development
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# .env.production
NEXT_PUBLIC_API_URL=https://api.example.com

Не коммитьте .env.local и .env.*.local в репозиторий — добавьте их в .gitignore.

Шаг 3: Добавление переменных в .gitignore

Убедитесь, что файлы с секретами не попадут в git. В .gitignore должны быть строки:

.env*.local
.env.production

Файл .env с общими несекретными настройками можно коммитить, но лучше не хранить там чувствительные данные.

Шаг 4: Использование переменных в серверном коде

В серверных компонентах, API routes и функциях getServerSideProps доступны все переменные из process.env:

// app/api/route.js
export async function GET() {
  const dbUrl = process.env.DATABASE_URL;
  // ...
}

В Pages Router:

export async function getServerSideProps() {
  const secret = process.env.SECRET_KEY;
  return { props: { data: 'ok' } };
}

Серверные переменные не попадают в клиентский бандл.

Шаг 5: Использование клиентских переменных

Переменные с префиксом NEXT_PUBLIC_ доступны в браузере. Их можно использовать в компонентах, хуках и любом клиентском коде:

// components/MyComponent.js
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Помните: значение встраивается на этапе сборки. Если вы измените переменную после сборки, в клиентском коде останется старое значение.

Шаг 6: Настройка переменных для production-сборки

При выполнении next build Next.js загружает .env.production (и .env.local, если есть). Убедитесь, что в .env.production указаны правильные значения для продакшена.

Пример .env.production:

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgres://prod-user:pass@prod-host:5432/prod-db

Не храните этот файл в открытом репозитории. Для CI/CD используйте секреты платформы.

Шаг 7: Передача переменных через CI/CD и хостинг

На большинстве платформ (Vercel, Netlify, AWS, Docker) переменные окружения задаются в настройках проекта или через секреты CI/CD.

Vercel: добавьте переменные в разделе Settings → Environment Variables. Они будут доступны на этапе сборки и в runtime.

Docker: используйте --env-file или -e при запуске контейнера. Например:

docker run --env-file .env.production my-next-app

GitHub Actions: храните секреты в Settings → Secrets and variables → Actions и передавайте их в шаги сборки.

Шаг 8: Проверка переменных на этапе сборки

Next.js встраивает клиентские переменные при сборке. Если переменная не задана, в бандл попадёт undefined. Чтобы избежать ошибок, можно добавить проверку в next.config.js:

// next.config.js
if (!process.env.NEXT_PUBLIC_API_URL) {
  throw new Error('NEXT_PUBLIC_API_URL is not defined');
}

Это остановит сборку, если критичная переменная отсутствует.

Шаг 9: Безопасность: не допускайте утечек

Никогда не используйте префикс NEXT_PUBLIC_ для секретов.
Не передавайте серверные переменные в клиентские компоненты через props, если они не предназначены для публичного доступа.
Регулярно проверяйте, какие переменные попадают в клиентский бандл (например, с помощью grep по собранным файлам).
Используйте разные значения для development и production.

Шаг 10: Работа с переменными в монорепозиториях

Если у вас монорепозиторий (например, с Turborepo), Next.js загружает .env из корня приложения. Убедитесь, что пути корректны, и при необходимости используйте dotenv для загрузки из общего места.

Шаг 11: Тестирование конфигурации

Перед деплоем проверьте, что все необходимые переменные заданы. Запустите сборку локально с production-окружением:

NODE_ENV=production next build

Убедитесь, что приложение запускается и переменные доступны.

Шаг 12: Обновление переменных без пересборки

Серверные переменные читаются в runtime, поэтому их можно изменить без пересборки (например, перезапустив контейнер). Клиентские переменные встраиваются при сборке — для их изменения потребуется новая сборка и деплой.

Типичные ошибки

1. Использование `NEXT_PUBLIC_` для секретов — приводит к утечке данных. 2. Забыли добавить `.env.local` в `.gitignore` — секреты попадают в репозиторий. 3. Ожидание, что клиентские переменные обновятся без пересборки — они встраиваются на этапе сборки. 4. Отсутствие проверки обязательных переменных — приложение падает в runtime. 5. Использование `.env` для production-секретов — файл может быть закоммичен. 6. Неправильный порядок загрузки — .env.local переопределяет .env.production, что может привести к неожиданностям.

FAQ

В: Можно ли использовать переменные без префикса в клиентском коде? О: Нет, они будут undefined. Next.js заменяет только переменные с префиксом NEXT_PUBLIC_.

В: Как передать серверную переменную в клиентский компонент? О: Только через props или API. Не используйте process.env напрямую в клиентском коде для серверных переменных.

В: Что делать, если переменная не загружается? О: Проверьте имя файла, расположение (корень проекта), перезапустите dev-сервер. Убедитесь, что переменная не пустая.

В: Можно ли использовать `.env.production` в git? О: Не рекомендуется, если там есть секреты. Лучше передавать переменные через CI/CD.

В: Как задать переменные для разных сред на Vercel? О: В настройках проекта можно указать разные значения для Production, Preview и Development.

Итог

Правильная настройка переменных окружения в Next.js для продакшена включает: разделение серверных и клиентских переменных, использование соответствующих .env файлов, передачу секретов через CI/CD и проверку конфигурации перед деплоем. Следуя этому руководству, вы избежите утечек данных и обеспечите стабильную работу приложения в production.