Переменные окружения (Environment Variables)

Коротко: Значения конфигурации (API-ключи, URL баз данных, секреты), задаваемые вне кода — например, в панели Vercel, а не жёстко прописанные в репозитории.

Подробнее: Некоторые значения (например, строки подключения к базе данных) можно в любое время снова посмотреть в соответствующей панели; другие (например, API-ключи) показываются только один раз при создании и при потере должны быть сгенерированы заново. У Vercel дополнительно есть флаг «Sensitive»: после его установки значение больше никто не может получить — даже через CLI (vercel env pull) или владелец команды.

Подробности

Локальная конфигурация

Локально в Next.js переменные окружения обычно задаются через файл .env.local (по соглашению никогда не коммитится, исключается в .gitignore — иначе секреты попадут в историю Git, где останутся доступными, даже если файл позже удалить, так как история Git по умолчанию ничего не забывает). Next.js автоматически читает несколько файлов .env* в фиксированном порядке приоритета (.env.local переопределяет .env.development/.env.production, которые, в свою очередь, переопределяют .env) — удобно, чтобы чисто разделить локальные значения разработки и реальные значения production, не смешивая их в одном файле.

Префикс NEXT_PUBLIC_

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

DATABASE_URL=postgresql://...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...  # намеренно публичный, для клиентского Stripe.js
STRIPE_SECRET_KEY=sk_live_...                    # остаётся на сервере

Разделение окружений в Vercel

В Vercel значения дополнительно управляются отдельно для каждого окружения (production/preview/development) — предварительный деплой (preview deploy) может, например, работать с тестовой базой данных вместо реальной production-базы, без необходимости что-либо различать в коде. Это особенно ценно в деструктивных тестовых сценариях: preview-деплой, случайно удаляющий или изменяющий тестовые данные, никогда не затронет реальную production-базу, пока разделение окружений строго соблюдается.

Флаг «Sensitive»

У Vercel дополнительно есть флаг «Sensitive»: после установки значение больше никто не может получить — даже через CLI (vercel env pull) или владелец команды. Это сознательная улица с односторонним движением: значение по-прежнему может использоваться приложением во время выполнения, но никто не может потом прочитать его открытым текстом, даже с полными административными правами на проект. На практике это означает: прежде чем задать чувствительное значение как «Sensitive», его следует надёжно сохранить в другом месте (например, в менеджере паролей) — потерянное чувствительное значение можно восстановить только полной перегенерацией у исходного провайдера, а не повторным чтением из Vercel.

См. также: Vercel, Bearer-токен