Пошук уроків, статей та іншого контенту
Дізнаєтеся, як зберігати секрети й налаштування в змінних середовища для різних оточень.
Змінні середовища — це значення, які передаються програмі ззовні. Їх використовують для:
секретних ключів;
паролів і токенів;
адрес зовнішніх API;
налаштувань, що відрізняються в development і production;
параметрів підключення до бази даних.
Наприклад, адреса API під час локальної розробки може бути такою:
http://localhost:4000А в production — іншою:
https://api.example.comЗамість зміни коду для кожного оточення можна зберігати ці значення у файлах змінних середовища.
У Next.js змінні зазвичай зберігають у файлах у корені проєкту:
.env
.env.local
.env.development
.env.development.local
.env.production
.env.production.local
.env.test
.env.test.localНайчастіше використовують такі файли:
.env.local — локальні значення розробника;
.env.development — значення для режиму розробки;
.env.production — значення для production;
.env.example — приклад потрібних змінних без секретних значень.
Файл .env.local зазвичай не додають до Git, оскільки він може містити секрети.
.env.localDATABASE_URL=postgresql://localhost:5432/shop
API_TOKEN=local-secret-token
NEXT_PUBLIC_API_URL=http://localhost:4000Формат простий: ім’я змінної, знак =, значення.
Не потрібно додавати пробіли навколо знака =:
# Правильно
API_TOKEN=my-token
# Небажано
API_TOKEN = my-tokenЯкщо значення містить пробіли, його можна взяти в лапки:
APP_NAME="Мій інтернет-магазин"У Next.js змінні середовища доступні через process.env:
const apiUrl = process.env.API_URL;Значення, отримане з process.env, має тип string | undefined. Змінна може бути не визначена, тому важливі налаштування варто перевіряти.
Файл app/page.js:
export default function HomePage() {
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
const appName = process.env.APP_NAME || "Мій застосунок";
return (
<main>
<h1>{appName}</h1>
<p>API: {apiUrl}</p>
</main>
);
}Файл .env.local:
APP_NAME="Каталог товарів"
NEXT_PUBLIC_API_URL=http://localhost:4000Запустіть застосунок у режимі розробки:
npm run devПісля цього Next.js прочитає значення з .env.local.
Після створення або зміни файлу змінних середовища перезапустіть сервер розробки.
У Next.js важливо розрізняти два типи змінних.
Змінні без префікса NEXT_PUBLIC_ призначені для серверного коду:
DATABASE_URL=postgresql://localhost:5432/shop
API_TOKEN=secret-tokenЇх можна використовувати в:
Server Components;
Route Handlers;
серверних функціях;
іншому коді, який не потрапляє в браузер.
Наприклад:
export async function GET() {
const token = process.env.API_TOKEN;
if (!token) {
return Response.json(
{ error: "API_TOKEN не налаштовано" },
{ status: 500 }
);
}
const response = await fetch("https://api.example.com/products", {
headers: {
Authorization: `Bearer ${token}`,
},
});
if (!response.ok) {
return Response.json(
{ error: "Не вдалося отримати товари" },
{ status: response.status }
);
}
const products = await response.json();
return Response.json(products);
}У цьому прикладі токен використовується на сервері та не передається безпосередньо браузеру.
Якщо змінна має бути доступною в клієнтському коді, її ім’я повинно починатися з NEXT_PUBLIC_:
NEXT_PUBLIC_API_URL=https://api.example.comТаку змінну можна використати у Client Component:
"use client";
export default function ApiStatus() {
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
return <p>Клієнтський API: {apiUrl}</p>;
}Префікс NEXT_PUBLIC_ означає, що значення не є секретом. Воно може потрапити до JavaScript-коду, який завантажує браузер.
Не можна зберігати під таким префіксом:
NEXT_PUBLIC_PASSWORD=my-password
NEXT_PUBLIC_API_TOKEN=secret-tokenЦі значення стануть доступними користувачам застосунку.
Для режиму розробки можна створити .env.development:
NEXT_PUBLIC_API_URL=http://localhost:4000
APP_NAME="Каталог — розробка"Для production — .env.production:
NEXT_PUBLIC_API_URL=https://api.example.com
APP_NAME="Каталог"Команда:
npm run devзазвичай запускає Next.js у режимі development.
Команда:
npm run build
npm run startвикористовує production-конфігурацію.
Локальні файли мають вищий пріоритет. Наприклад, значення з .env.development.local матиме перевагу над значенням з .env.development.
Загальний порядок пріоритету такий:
уже наявна змінна process.env;
.env.<режим>.local;
.env.local;
.env.<режим>;
.env.
Тому у .env.development.local можна зберігати особисті локальні налаштування, які не повинні потрапити до спільного репозиторію.
.env.exampleЩоб інші розробники знали, які змінні потрібні проєкту, створіть .env.example:
APP_NAME=
DATABASE_URL=
API_TOKEN=
NEXT_PUBLIC_API_URL=У цей файл не додають справжні секрети. Він описує лише назви необхідних змінних.
Інший розробник може створити власний .env.local на основі цього прикладу:
APP_NAME="Локальний каталог"
DATABASE_URL=postgresql://localhost:5432/shop
API_TOKEN=local-token
NEXT_PUBLIC_API_URL=http://localhost:4000Якщо змінна потрібна для роботи сервера, краще перевірити її під час запуску або виконання серверного коду.
function getRequiredEnv(name) {
const value = process.env[name];
if (!value) {
throw new Error(`Не задано змінну середовища: ${name}`);
}
return value;
}
export async function GET() {
const databaseUrl = getRequiredEnv("DATABASE_URL");
return Response.json({
configured: Boolean(databaseUrl),
});
}Так помилка буде зрозумілою. Без перевірки застосунок може впасти пізніше з менш очевидною помилкою.
Не повертайте секрет у відповіді:
// Небезпечно
return Response.json({
token: process.env.API_TOKEN,
});Навіть серверний Route Handler може віддати це значення клієнту через HTTP-відповідь.
Структура мінімального проєкту:
app/
page.js
api/
config/
route.js
.env.local
.env.exampleФайл .env.local:
APP_NAME="Мій каталог"
API_TOKEN=local-secret-token
NEXT_PUBLIC_API_URL=http://localhost:4000Файл app/page.js:
export default function HomePage() {
const appName = process.env.APP_NAME || "Застосунок";
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
return (
<main>
<h1>{appName}</h1>
<p>Адреса API: {apiUrl}</p>
<p>Секретний токен використовується лише на сервері.</p>
</main>
);
}Файл app/api/config/route.js:
export async function GET() {
const token = process.env.API_TOKEN;
if (!token) {
return Response.json(
{ error: "API_TOKEN не налаштовано" },
{ status: 500 }
);
}
return Response.json({
configured: true,
});
}Маршрут /api/config повідомляє лише, що токен налаштований. Сам токен не потрапляє у відповідь.
Значення NEXT_PUBLIC_* вбудовуються у клієнтський JavaScript під час виконання next build. Якщо змінити їх після збирання, уже зібраний клієнтський код може продовжити використовувати старе значення.
Тому для іншого production-оточення часто потрібно виконати нове збирання із правильними значеннями.
Секретні змінні використовуйте в серверному коді:
const token = process.env.API_TOKEN;Не передавайте їх у:
JSX, який рендериться для браузера;
JSON-відповіді API;
властивості Client Components;
повідомлення, що показуються користувачу.
.env.local не слід додавати до GitПереконайтеся, що файл із локальними секретами ігнорується Git. У типовому Next.js-проєкті це вже налаштовано у .gitignore.
Якщо секрет випадково потрапив у репозиторій, простого видалення файлу недостатньо: секрет потрібно замінити або відкликати в сервісі, якому він належить.
NEXT_PUBLIC_NEXT_PUBLIC_DATABASE_PASSWORD=secretБудь-який користувач може побачити це значення у клієнтському коді. Для секретів використовуйте імена без NEXT_PUBLIC_.
Після зміни .env.local уже запущений сервер розробки може не підхопити нове значення. Перезапустіть його.
Файл .env.local повинен бути в корені Next.js-проєкту, поруч із package.json:
my-next-app/
app/
package.json
.env.localНавіть якщо секрет не показується на сторінці, він може потрапити в логи:
console.log(process.env.API_TOKEN);Не виводьте токени, паролі та ключі в консоль або журнали production-сервера.
Якщо код очікує наявність змінної, але її немає, помилка може виникнути далеко від місця конфігурації. Перевіряйте обов’язкові значення та повертайте зрозуміле повідомлення про проблему.
Змінні середовища зберігають секрети та налаштування поза кодом.
У Next.js змінні читаються через process.env.
.env.local зручно використовувати для локальних значень.
.env.development і .env.production дають змогу налаштувати різні оточення.
Змінні без NEXT_PUBLIC_ призначені для серверного коду.
Змінні з NEXT_PUBLIC_ доступні браузеру й не повинні містити секретів.
.env.local не слід додавати до Git.
Після зміни файлів змінних середовища перезапускайте сервер розробки.
Для обов’язкових змінних створюйте перевірку, а секрети ніколи не повертайте клієнту.