Environment Variables на Vercel: как не сломать прод

В этом материале

• Что такое env-переменные.
• Как они работают на Vercel.
• Как их правильно настраивать.
• Чем отличаются Production, Preview и Development.
• Как работает `NEXT_PUBLIC_` в Next.js.
• Почему переменная может не работать после сохранения.
• Как безопасно диагностировать env без утечки секретов.
• Частые ошибки.
• Чеклист перед деплоем.

Что это такое

Environment variables — это переменные окружения для настройки проекта без хранения секретов в коде.

Они используются для API-ключей, токенов, URL, cookie-секретов, OAuth-настроек, адресов backend API и конфигурации базы данных.

Если в коде есть обращение к `process.env.DATABASE_URL`, значение должно приходить из окружения, а не из публичного файла в репозитории.

Как это работает

На Vercel обычно используются три среды: Development, Preview и Production.

Для каждой среды можно задать отдельные значения переменных.

Во время сборки и выполнения Vercel подставляет эти значения в приложение.

Важно: изменение env-переменной не переписывает уже существующий deployment. Чтобы новая переменная попала в сайт, нужен новый deploy или redeploy.

Где добавить переменные в Vercel

Откройте нужный проект в Vercel, затем Project Settings → Environment Variables.

Для каждой переменной укажите Name, Value и выберите среду: Production, Preview, Development или несколько сред сразу.

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

Если переменная нужна в production, убедитесь, что она добавлена именно в Production, а не только в Preview.

Production, Preview и Development

Production — это рабочий сайт на основном домене. Ошибка в этой среде сразу влияет на пользователей.

Preview — это проверки pull request, веток и временных ссылок. Здесь удобно тестировать новую конфигурацию до выката.

Development — локальная разработка через Vercel CLI и `.env.local`. Значения здесь могут отличаться от production.

Типичная ошибка: переменная добавлена в Preview, preview работает, но production после релиза падает, потому что в Production значения нет.

Пошаговая инструкция

Ниже базовая схема настройки env-переменных на Vercel для стабильного production-деплоя.

1. Определить, какие переменные нужны

Важно хранить только нужные переменные и не создавать лишние.

Отдельно выпишите, какие переменные нужны на этапе build, а какие только во время runtime. Build-time переменные должны существовать уже во время сборки.

• API_URL
• TOKEN
• DATABASE_URL

2. Добавить переменные в Vercel

В проекте откройте Settings → Environment Variables.

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

Если это секретный токен, не вставляйте его в код, README, GitHub issue, комментарии к PR или сообщение AI-ассистенту.

3. Проверить названия

Частая ошибка — неверное имя переменной.

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

Проверьте пробелы, кавычки, дефисы вместо подчеркивания и разные варианты вроде `API_KEY`, `NEXT_PUBLIC_API_KEY`, `VERCEL_API_KEY`.

4. Проверить client и server переменные

В Next.js клиентские переменные должны начинаться с NEXT_PUBLIC.

Серверные переменные не должны использоваться в клиентском коде.

`NEXT_PUBLIC_` означает, что значение может попасть в browser bundle. Поэтому токены, service role keys, database URLs и private API keys нельзя хранить с таким префиксом.

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

`.env.local` и локальная разработка

Файл `.env.local` нужен для локальной разработки и не заменяет настройки Vercel Production.

Он должен быть в `.gitignore`, потому что там часто лежат ключи, токены и локальные URL.

Если локально все работает, а production нет, сравните не значения секретов, а список имен переменных: какие есть локально и какие добавлены в Vercel.

5. Перезапустить деплой

После изменения env-переменных нужно сделать redeploy, иначе новые значения не применятся к уже созданному deployment.

Если вы обновили переменную и проверяете старую ссылку деплоя, она может продолжать работать со старым окружением.

6. Проверить работу

• Работает ли API.
• Нет ли ошибок в runtime.
• Корректно ли подставились значения.
• Не попал ли секрет в клиентский bundle.
• Не выводится ли полный токен в логах.

Почему переменная не работает

Если симптом похож на падение сборки, переходите к материалу про ошибки сборки на Vercel. Если проблема появляется только после релиза, дополнительно проверьте диагностику 404/500 после deploy.

• Переменная добавлена в Preview, но проверяется Production.
• После изменения не был выполнен redeploy.
• Имя в коде отличается от имени в Vercel.
• Есть лишний пробел, кавычка или перенос строки в value.
• Build-time переменная отсутствует во время сборки.
• Секретная переменная ошибочно читается в client component.
• `NEXT_PUBLIC_` добавлен или убран не там, где нужно.
• Проверяется старый deployment, а не последний production build.

Безопасная диагностика env

Нельзя печатать полный токен, DATABASE_URL или service role key в консоль, лог Vercel, GitHub Actions или чат с AI.

Безопасный вариант — проверять только факт наличия, длину значения, boolean-флаг или маскированный префикс без раскрытия секрета.

Например, вместо полного значения логируйте `hasToken: true`, `tokenLength: 48` или `databaseUrlConfigured: true`.

Если секрет случайно попал в публичный лог или репозиторий, его нужно ротировать, а не просто удалить строку из кода.

Какие значения нельзя делать публичными

Публичными могут быть только значения, которые безопасно видеть пользователю в браузере. Если есть сомнение, считайте переменную server-only.

• Database connection string.
• Supabase service role key.
• Stripe secret key.
• Telegram bot token.
• Vercel token.
• GitHub token.
• Cookie signing secret.
• Private API keys для AI-провайдеров.

Чеклист перед деплоем

• Все переменные добавлены.
• Названия совпадают.
• Переменные назначены в нужные среды.
• Production-переменные проверены отдельно от Preview.
• Client и server переменные разделены.
• Секреты не используют `NEXT_PUBLIC_`.
• `.env.local` не коммитится.
• Значения актуальны.
• Лишние переменные удалены или отключены.
• Проверка не раскрывает секреты в логах.
• Выполнен redeploy.

Где это применяется

• Next.js проекты.
• Сайты на Vercel.
• API-интеграции.
• Telegram-боты.
• Mini App.
• AI-проекты.

Частые ошибки

• Забыли добавить переменную в Vercel.
• Неправильное имя переменной.
• Перепутали среды dev, preview и prod.
• Не сделали redeploy после изменений.
• Используют server env в client.
• Сделали приватный токен публичным через `NEXT_PUBLIC_`.
• Хранят секреты в коде.
• Отправляют секреты в AI-чат или вставляют их в issue.

Как env связаны с CI/CD

Если проект деплоится через GitHub Actions, секреты должны храниться в GitHub Secrets или в Vercel, а не в workflow-файле.

Для настройки проверок и безопасного production deploy смотрите GitHub Actions + Vercel: CI/CD для новичка пошагово.

Перед релизом полезно пройти Как тестировать код от Codex без глубокого программирования, чтобы поймать env и build-проблемы до production.

Почему это важно

Ошибки env — одна из главных причин падения production, неработающих API и странных отличий между локальной и live-версией.

Если переменные настроены корректно, деплой проходит стабильнее, а интеграции работают предсказуемо.

Для понимания, что именно скрывается за API-ключами и запросами к сервисам, можно отдельно разобрать что такое API.

Вывод

Environment variables — критическая часть проекта, а не второстепенная настройка.

Чтобы не ломать прод, важно внимательно задавать переменные, проверять имена, разделять client и server, делать redeploy и тестировать после изменения окружения.

Внутренняя перелинковка

Для диагностики симптомов после релиза сначала проверьте Почему после деплоя 404/500 и как быстро починить.

Если деплой падает на сборке, изучите Ошибки сборки на Vercel: как исправлять через Codex.

Если нужны автоматические проверки до production, откройте GitHub Actions + Vercel: CI/CD для новичка пошагово.

Если нужно быстро восстановить сайт, смотрите Как откатить неудачный деплой на Vercel за 5 минут.

Перед релизом полезно пройти Как тестировать код от Codex без глубокого программирования.