Переменные окружения

Переменные окружения — настройки, которые различаются на вашем компьютере и на сервере: путь к базе данных, ключи API, адрес сайта. Их не пишут в код, а кладут в файл .env.local, который не попадает в Git.

Файл .env.local

Создайте файл .env.local в корне проекта, рядом с package.json:

DATABASE_FILE=blog.db
API_SECRET=k3y-for-local-tests
NEXT_PUBLIC_SITE_NAME=Мой блог

Next.js читает этот файл при запуске. После правки .env.local перезапустите npm run dev.

Чтение на сервере

В серверном коде переменная доступна через process.env:

// db/index.ts
import Database from 'better-sqlite3';
import { drizzle } from 'drizzle-orm/better-sqlite3';
 
export const db = drizzle({ client: new Database(process.env.DATABASE_FILE ?? 'blog.db') });

Теперь имя файла базы задаётся настройкой: на сервере можно указать другой путь, не меняя код. Тип у process.env.DATABASE_FILE — string | undefined, поэтому стоит значение по умолчанию.

Правило NEXT_PUBLIC_

В браузер попадают только переменные, имя которых начинается с NEXT_PUBLIC_. Next.js при сборке подставляет их значения прямо в код:

// components/SiteName.tsx
'use client';
 
export default function SiteName() {
  return <span>{process.env.NEXT_PUBLIC_SITE_NAME}</span>;
}

Компонент покажет «Мой блог». Если бы переменная называлась SITE_NAME, в клиентском компоненте она была бы undefined.

Переменная	Сервер	Браузер
`API_SECRET`	Да	Нет
`NEXT_PUBLIC_SITE_NAME`	Да	Да, значение видно всем

Поэтому секреты — пароли, ключи платёжных систем — никогда не называют с NEXT_PUBLIC_.

Какие файлы бывают

Файл	Когда читается	В Git
`.env`	Всегда	Можно, без секретов
`.env.development`	При `npm run dev`	Можно, без секретов
`.env.production`	При `npm run build` и `start`	Можно, без секретов
`.env.local`	Всегда, важнее остальных	Нет

Стартовый .gitignore исключает все файлы .env*; чтобы хранить в Git файл без секретов, например .env, уберите его из этого правила. На хостинге переменные обычно задают в панели управления, а не файлом.

Частая ошибка

Изменить значение NEXT_PUBLIC_ переменной на сервере и ждать, что сайт его подхватит. Такие значения вшиваются в JavaScript во время npm run build. После изменения переменной с NEXT_PUBLIC_ проект нужно собрать заново.

Спасибо, что читаете!