Змінні середовища (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-токен