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

Введение

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

Требования

• Проект на Next.js (версии 12+; примеры актуальны для 13/14 с App Router, но подход работает и для Pages Router).

• Node.js версии 18 или выше.

• Доступ к серверу или платформе деплоя (Vercel, Netlify, Docker, VPS и т.п.).

• Базовое понимание работы с командной строкой и Git.

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

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

• Без префикса — доступны только на сервере (в getServerSideProps, API-роутах, серверных компонентах).

• С префиксом `NEXT_PUBLIC_` — встраиваются в клиентский JavaScript и доступны в браузере.

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

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

Next.js поддерживает несколько файлов окружения:

• .env — загружается всегда.

• .env.local — загружается всегда, кроме тестового окружения; обычно используется для локальных секретов и не коммитится в Git.

• .env.development — для режима разработки.

• .env.production — для продакшен-сборки.

Порядок загрузки: .env.$(NODE_ENV).local → .env.local → .env.$(NODE_ENV) → .env. Переменные из файлов с более высоким приоритетом перезаписывают предыдущие.

Важно: файлы .env.local и любые файлы с секретами не должны попадать в репозиторий. Добавьте их в .gitignore.

Шаг 3: Настройка переменных для локальной разработки

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

DATABASE_URL=postgres://user:pass@localhost:5432/mydb
NEXT_PUBLIC_API_URL=http://localhost:3000/api
SECRET_KEY=dev-secret

Запустите npm run dev — Next.js автоматически загрузит эти значения. Используйте их в коде через process.env.DATABASE_URL (на сервере) и process.env.NEXT_PUBLIC_API_URL (на клиенте).

Шаг 4: Определение переменных для продакшена

Для продакшена создайте .env.production (если хотите хранить значения в репозитории — но только для несекретных данных) или задайте переменные через панель управления хостингом. Например, на Vercel: Project Settings → Environment Variables. В Docker: через --env-file или environment в docker-compose.

Рекомендуется следующий подход:

• Публичные переменные (NEXT_PUBLIC_*) можно хранить в .env.production.

• Секретные переменные задавайте только через защищённые хранилища (Vercel Env, AWS Secrets Manager, GitHub Secrets и т.п.).

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

На сервере (API-роут, серверный компонент, getServerSideProps):

export async function GET() {
  const apiKey = process.env.SECRET_KEY;
  // ...
}

На клиенте (в компоненте, в браузере):

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

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

Шаг 6: Валидация переменных при старте

Чтобы избежать ошибок в рантайме, проверяйте наличие обязательных переменных при запуске приложения. Можно использовать библиотеку zod или простую функцию:

const requiredEnv = ['DATABASE_URL', 'SECRET_KEY'];
requiredEnv.forEach((key) => {
  if (!process.env[key]) {
    throw new Error(`Missing environment variable: ${key}`);
  }
});

Этот код можно разместить в отдельном модуле и импортировать в next.config.js или в серверной точке входа.

Шаг 7: Настройка next.config.js

В next.config.js можно использовать переменные окружения для динамической конфигурации. Например:

module.exports = {
  env: {
    CUSTOM_VAR: process.env.CUSTOM_VAR,
  },
};

Однако учтите: всё, что попадает в env, будет доступно на клиенте. Лучше использовать NEXT_PUBLIC_ префикс.

Шаг 8: Деплой на Vercel

Vercel автоматически подхватывает переменные из настроек проекта. Добавьте их для окружений Production, Preview и Development. При сборке Vercel использует значения из Production для продакшен-деплоя. Убедитесь, что переменные с префиксом NEXT_PUBLIC_ заданы до сборки, иначе они не попадут в бандл.

Шаг 9: Деплой в Docker

При сборке Docker-образа переменные можно передать через ARG и ENV. Пример Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm ci
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
RUN npm run build
CMD ["npm", "start"]

Секретные переменные не следует передавать на этапе сборки — их лучше задавать при запуске контейнера через docker run --env-file .env.production.

Шаг 10: Работа с секретами в CI/CD

В GitHub Actions, GitLab CI и других системах используйте защищённые переменные. Например, в GitHub Actions:

jobs:
  build:
    steps:
      - run: npm run build
        env:
          NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
          SECRET_KEY: ${{ secrets.SECRET_KEY }}

Никогда не выводите секреты в логи. Для этого можно маскировать их с помощью ::add-mask::.

Шаг 11: Проверка после деплоя

После развёртывания убедитесь, что:

• Приложение запускается без ошибок, связанных с отсутствием переменных.

• Публичные переменные корректно встроены в клиентский бандл (проверьте через DevTools → Sources).

• Секретные переменные недоступны в браузере.

• Все серверные запросы используют правильные значения.

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

1. Использование `NEXT_PUBLIC_` для секретов. Это приводит к утечке ключей в клиентский код. 2. Забыли добавить переменную в окружение продакшена. Приложение может работать локально, но упасть на сервере. 3. Изменение переменных после сборки. Next.js встраивает NEXT_PUBLIC_* на этапе сборки, поэтому для применения изменений нужна пересборка. 4. Хранение `.env.local` в Git. Это раскрывает секреты. 5. Отсутствие валидации. Приложение падает с неинформативной ошибкой. 6. Использование `env` в next.config.js для секретов. Они становятся доступны на клиенте.

FAQ

В: Можно ли использовать переменные окружения в getStaticProps? О: Да, но только на сервере во время сборки. Значения будут встроены в статический HTML.

В: Как обновить NEXT_PUBLIC_ переменные без пересборки? О: Никак. Они встраиваются в бандл при сборке. Для динамических значений используйте API-роуты.

В: Что делать, если переменная не подхватывается на Vercel? О: Проверьте, что она добавлена для нужного окружения (Production/Preview/Development) и что сборка запущена после добавления.

В: Можно ли использовать .env.production в Git? О: Только если там нет секретов. Лучше хранить секреты в защищённых хранилищах.

В: Как передать переменные в Docker при сборке? О: Используйте ARG для публичных переменных и ENV для рантайма. Секреты передавайте при запуске контейнера.

Итог

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