Змінні середовища в Next.js

Next.js має вбудовану підтримку змінних середовища з особливими умовами для тільки серверних та публічних (доступних для клієнта) змінних.

Конвенції файлів

.env                → Усі середовища
.env.local          → Локальні переопрацювання (ігнорується git)
.env.development    → Тільки для розробки
.env.production     → Тільки для продакшну
.env.test           → Тільки для тестування

Пріоритет (від найвищого до найнижчого): .env.local > .env.[середовище] > .env

Серверні та клієнтські змінні

bash

# .env.local

# ✅ Тільки серверні (за замовчуванням) — НЕ доступні в браузері
DATABASE_URL=postgresql://localhost:5432/mydb
JWT_SECRET=super-secret-key
API_KEY=sk-1234567890

# ✅ Публічні — доступні в браузері (префікс NEXT_PUBLIC_)
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_live_xxx

Використання

tsx

// Серверний компонент або API маршрут — має доступ до ВСІХ змінних
async function ServerComponent() {
  const dbUrl = process.env.DATABASE_URL;           // ✅ Доступно
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;    // ✅ Доступно
  const secret = process.env.JWT_SECRET;             // ✅ Доступно
}

// Клієнтський компонент — ТІЛЬКИ змінні NEXT_PUBLIC_
"use client";
function ClientComponent() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;    // ✅ Доступно
  const dbUrl = process.env.DATABASE_URL;            // ❌ undefined!
  const secret = process.env.JWT_SECRET;             // ❌ undefined!
}

Важливі правила

Правило	Деталі
За замовчуванням — тільки серверні	Змінні без `NEXT_PUBLIC_` є тільки серверними
Префікс `NEXT_PUBLIC_`	Необхідний для надання змінної браузеру
Статична заміна	Змінні `NEXT_PUBLIC_` вбудовуються під час збірки
`.env.local` ігнорується git	Використовуйте для секретів, переопрацювання для кожного розробника
Потрібен перезапуск	Зміни у файлах `.env` вимагають перезапуску сервера розробки

Статична заміна (під час збірки)

Змінні NEXT_PUBLIC_ замінюються на етапі збірки, а не під час виконання:

tsx

// ✅ Це працює — пряме посилання
const url = process.env.NEXT_PUBLIC_API_URL;

// ❌ Це НЕ працює — динамічний доступ
const key = "NEXT_PUBLIC_API_URL";
const url = process.env[key]; // undefined в клієнті!

Безпека типів з TypeScript

typescript

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    DATABASE_URL: string;
    JWT_SECRET: string;
    NEXT_PUBLIC_API_URL: string;
    NEXT_PUBLIC_GA_ID: string;
    NODE_ENV: "development" | "production" | "test";
  }
}

Змінні середовища під час виконання

Для змінних, які потрібно змінювати після збірки (наприклад, у Docker):

tsx

// next.config.js
module.exports = {
  // Змінні середовища на стороні сервера
  serverRuntimeConfig: {
    apiSecret: process.env.API_SECRET,
  },
  // Доступні як на сервері, так і на клієнті
  publicRuntimeConfig: {
    apiUrl: process.env.API_URL,
  },
};

Найкращі практики безпеки

Ніколи не розміщуйте секрети у змінних NEXT_PUBLIC_
Завжди використовуйте .env.local для чутливих значень
Додайте .env.local до .gitignore
Надати .env.example з заповнювачами для команди
Використовуйте декларації TypeScript для безпеки типів

Важливо:

За замовчуванням, змінні середовища в Next.js є тільки серверними і не доступні в браузері. Використовуйте префікс NEXT_PUBLIC_, щоб явно зробити змінну доступною на клієнті. Пам'ятайте, що публічні змінні вбудовуються під час збірки і не можуть бути змінені без повторної збірки. Ніколи не розкривайте секрети за допомогою NEXT_PUBLIC_.

Коротка відповідь

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.

Дочитали статтю?

Практика завдань