7 мин чтения

.env — куда складывать секреты

У вас в коде нельзя писать `const KEY = "sk-proj-..."` — потому что когда запушите в гит, ключ уйдёт в публичный архив. Поэтому ключи живут отдельно от кода — в файле `.env`, который игнорируется гитом. Код только ЧИТАЕТ из этого файла через `process.env.ИМЯ`.

Как устроен .env

Это просто текстовый файл в корне проекта. Внутри — пары КЛЮЧ=ЗНАЧЕНИЕ, по одной на строку. Без кавычек (если в значении нет пробелов). Без = вокруг знака равенства. Комментарии — через #. Имена принято писать UPPER_SNAKE_CASE: OPENAI_API_KEY, DATABASE_URL. Когда запускается

$ npm run dev

или next start, значения автоматически подгружаются в process.env.

Разные .env под разные среды

.env — общий, читается везде. .env.local — только локально, НЕ коммитится никогда. .env.development / .env.production — для соответствующего режима. .env.example — пустой шаблон с именами без значений, КОММИТИТСЯ в гит — чтобы коллега скачал и понял, какие переменные ему создать. Правило: реальные значения — только в .env.local, если речь про команду.

Что должно быть в .gitignore

Без .gitignore весь смысл .env теряется. Минимальный набор строк: .env, .env.local, .env.*.local. Современные шаблоны (create-next-app, vite create) добавляют их автоматически — но всегда проверяйте: откройте .gitignore, найдите эти строки. Если их нет — добавьте ДО первого коммита. Уже коммитили реальный .env? — отзывайте все ключи, чистите историю через

$ git filter-branch

или

$ BFG Repo-Cleaner

Как читать в коде

В Node.js / Next.js: process.env.OPENAI_API_KEY — возвращает строку или undefined. Восклицательный знак (!) в TypeScript говорит «я уверен, что значение есть». На практике лучше падать с понятной ошибкой:

$ if (!process.env.OPENAI_API_KEY) throw new Error("OPENAI_API_KEY не установлен")

Vite использует другой синтаксис: import.meta.env.VITE_API_URL.

примерbash

// .env файл в корне проекта — это просто текстовый файл.
// Формат: KEY=VALUE, по одной паре на строку.

// .env
OPENAI_API_KEY=sk-proj-abc123def456ghi789...
DATABASE_URL=postgresql://user:pass@host:5432/db
ADMIN_EMAIL=admin@example.com

// .gitignore (в корне проекта) ОБЯЗАТЕЛЬНО содержит:
.env
.env.local
.env.*.local

// В коде читаем через process.env.ИМЯ:
const key = process.env.OPENAI_API_KEY;
console.log(key);  // sk-proj-abc123...

// БЕЗ .env пришлось бы писать ключ прямо в коде.
// А потом пушнуть в GitHub. А потом плакать.

Структура .env и .gitignore — каноническая раскладка

главное

01.env живёт в корне проекта, формат КЛЮЧ=ЗНАЧЕНИЕ, без кавычек
02.gitignore ОБЯЗАН содержать .env и .env.local — иначе всё бессмысленно
03Имена в UPPER_SNAKE_CASE — это конвенция, не правило, но все так делают
04process.env.ИМЯ — для Node/Next, import.meta.env.ИМЯ — для Vite
05.env.example без реальных значений — коммитится для команды
06Изменили .env — перезапустите dev-сервер, иначе старое значение в памяти

проверь себя

01Куда положить ключ OpenAI в проекте Next.js, чтобы он работал и не утёк?

02Почему `.env.example` коммитится, а `.env` — нет?

03Поменяли значение в .env, но в коде всё равно старое. Что делать?

следующий урок: Серверные vs клиентские переменные — главная ловушка →