Перейти к содержимому

Настройки только в .env-файлах

Стандарт jcb-dotenv - v1.0 - 2026-11-16Скачать .md

Всё, что отличается между окружениями (адреса, порты, база, секреты, переключатели), лежит в .env-файлах. В коде нет значений по умолчанию для этих настроек: всё берётся из окружения. Если обязательной переменной нет, сервер не запускается и пишет, какой именно.

Файл В git Режим
.env.development да разработка
.env.test да автопроверки
.env.test.<вид> да только если нужно: вид проверок со своими серверами (например, сквозные)
.env.local нет личное поверх разработки: своя почта админа, ключи внешних служб, пароли
.env.production.example да шаблон для сервера: все переменные, секреты без значений

На сервере файлов нет: переменные задаются окружению процесса или контейнера.

  • У всех файлов один набор переменных в одном порядке, отличаются только значения. Ненужное в режиме — пусто. Новая переменная — сразу во все файлы.
  • Переключатели — словами из короткого списка: on|off, log|smtp, open|admins. Не 1/true/yes.
  • Переключатели задаются явно: нет значения или оно не из списка — сервер не стартует и называет переменную. Код не угадывает режим. В шаблоне для сервера у переключателей стоят боевые значения (лимиты on, тестовые ручки off), секреты — пустые.
  • Ключи внешней службы — не переключатель: их наличие и есть настройка. Все пустые — функции нет, все заданы — есть; отдельного on|off не нужно. Задана только часть ключей службы — сервер не стартует и называет недостающие.
  • Приоритет. Разработка: окружение оболочки > .env.local > .env.development. Автопроверки: файл главнее оболочки, .env.local не читается — проверки не зависят от того, что задано у человека.
  • Закоммиченные файлы — без боевых значений: секреты вида dev-secret-…/test-secret-…, адреса localhost / *.test, база локальная.
  • Правила продукта — в коде, а не в окружении: сроки, лимиты, длины. Окружение — только то, что меняется между местами запуска.
  • «test» — только автопроверки. Живой стенд перед боевым сайтом называется «staging» и получает свой шаблон.
  • Чтение — в одном модуле: он проверяет значения при старте, остальной код берёт их оттуда, а не из process.env напрямую.
  • Каждая переменная описана в одном документе проекта — docs/env.md: что делает, какие значения бывают, что стоит в каждом файле. У каждой переменной свой заголовок вида ### `ИМЯ` (несколько связанных — в одном: ### `SMTP_HOST`, `SMTP_PORT`). Оформление внутри раздела — на усмотрение проекта.

Автопроверка в проекте читает все файлы и требует:

  • одинаковый набор и порядок переменных во всех файлах;
  • каждая переменная, которую читает код, есть в файлах;
  • переключатели заданы во всех файлах и только из списка значений;
  • закоммиченные файлы без боевых значений; шаблон без секретов; в шаблоне тестовые ручки выключены, лимиты включены;
  • .env.local в .gitignore;
  • в docs/env.md у каждой переменной из файлов есть заголовок, и нет заголовков переменных, которых в файлах нет.
  • v1.0 — 2026-11-16: первая версия, из практики MoveTap.

JCB-NOTESdevИсходники на GitHubCC BY 4.0llms.txt