Змінні середовища (environment variables): навіщо й як правильно

Проблема: конфігурація, зашита в код

Якщо адреса бази даних чи ключ стороннього API прописані прямо в коді, застосунок неможливо запустити з іншими налаштуваннями (локально, на стейджингу, в проді) без редагування самого коду — а секретні ключі, потрапивши в git-репозиторій, лишаються в історії комітів назавжди, навіть якщо їх пізніше «видалити».

Принцип: конфігурація живе в середовищі, не в коді

Методологія 12-factor app формулює це прямо: конфігурація, що відрізняється між середовищами розгортання (адреси баз даних, ключі API, прапорці функцій), має зберігатись у змінних середовища операційної системи/процесу, а не в конфігураційних файлах усередині репозиторію коду.

javascript

// Node.js: process.env — вбудований доступ до змінних середовища процесу
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.SENDGRID_KEY;

if (!dbUrl) {
  throw new Error("DATABASE_URL не задано — перевірте .env файл");
}

Файли .env (курс Node.js, урок «Змінні середовища та конфігурація») дозволяють тримати ці значення локально під час розробки, не прописуючи їх у самому коді. Критично важливо: .env файли з реальними секретами додаються в .gitignore і ніколи не комітяться — у репозиторій потрапляє лише .env.example із назвами змінних без реальних значень.

NEXT_PUBLIC_: коли змінна потрапляє в браузер

У Next.js звичайні змінні середовища доступні лише на сервері — це свідомий захист від випадкового витоку секретів у клієнтський JavaScript-бандл. Якщо значення справді потрібне в браузері (наприклад, публічний ключ аналітики), змінну явно префіксують NEXT_PUBLIC_:

bash

# .env.local
DATABASE_URL=postgresql://user:pass@localhost:5432/app   # лише на сервері
NEXT_PUBLIC_ANALYTICS_ID=UA-12345                          # потрапляє і в браузер

Ніколи не додавайте префікс NEXT_PUBLIC_ до секретних значень (ключів API, паролів баз даних) — усе з цим префіксом Next.js під час збірки буквально вбудовує в JavaScript-файли, які завантажує браузер, тож будь-хто може прочитати значення через DevTools.

Змінні середовища в Docker

У контейнерах змінні задаються через environment у docker-compose.yml чи через --env-file (курс Docker, урок «Змінні середовища в контейнерах») — той самий принцип, що й поза контейнерами: конфігурація приходить ззовні образу, тож один і той самий образ можна запускати з різними налаштуваннями для різних середовищ, не перезбираючи його.

Поширені помилки

Комітити .env файл із реальними значеннями в git — навіть один випадковий коміт назавжди лишає секрет в історії репозиторію; його доведеться не просто видалити, а й ротувати (згенерувати новий ключ/пароль), бо старий вважається скомпрометованим.
Додавати NEXT_PUBLIC_ до змінної, не усвідомлюючи, що вона стане публічною, — поширена помилка новачків у Next.js, яка виглядає як звичайна конфігурація, але фактично публікує значення в браузері всіх користувачів.
Не мати значення за замовчуванням чи явної перевірки обов'язкових змінних під час старту застосунку — застосунок запускається «успішно», але падає з незрозумілою помилкою десь усередині першого запиту, коли вперше звертається до відсутньої змінної.

Підсумок

Змінні середовища відокремлюють конфігурацію (адреси сервісів, ключі API, прапорці) від коду застосунку, дозволяючи запускати той самий код з різними налаштуваннями в різних середовищах без змін у самому коді. .env файли зручні для локальної розробки, але секрети в них ніколи не потрапляють у git; у Next.js лише явно позначені NEXT_PUBLIC_-змінні стають доступні в браузері, а в Docker конфігурація передається через environment чи --env-file без перезбирання образу.