re:re:actable
Урок 062 минуты чтения

Как настроить переменные окружения и команды проекта?

На этой странице
Кратко

Адрес базы, порт и секреты должны приходить из окружения. При запуске приложение обязано сразу проверить, что обязательные значения существуют и имеют правильный формат.

Вопрос

Как хранить настройки и секреты Express-приложения? Зачем проверять переменные окружения при старте?

.env

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://app:password@localhost:5432/app_db
CLIENT_ORIGIN=http://localhost:5173

Создай безопасный пример без настоящих секретов:

# .env.example
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:password@localhost:5432/database
CLIENT_ORIGIN=http://localhost:5173

В Git отправляется .env.example, но не .env.

Проверка через Zod

// src/config/env.ts
import "dotenv/config";
import { z } from "zod";
 
const envSchema = z.object({
  NODE_ENV: z
    .enum(["development", "test", "production"])
    .default("development"),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().min(1),
  CLIENT_ORIGIN: z.string().url().default("http://localhost:5173"),
});
 
export const env = envSchema.parse(process.env);

Если DATABASE_URL отсутствует, сервер завершится при запуске с понятной ошибкой, а не упадёт во время первого запроса.

Команды package.json

{
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "type-check": "tsc --noEmit",
    "build": "tsc",
    "start": "node dist/server.js",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    "test": "vitest",
    "test:run": "vitest run"
  }
}

Обычный рабочий цикл

npm run dev
npm run type-check
npm run test:run
npm run build
npm start

Секреты

Никогда не записывай в исходный код:

  • пароль PostgreSQL;
  • ключ подписи токена;
  • пароль внешней службы;
  • настоящий адрес с секретами;
  • данные пользователей.

В системе автоматической проверки и на сервере значения задаются через защищённые настройки окружения.

Что важно помнить

  • Все значения process.env — строки или undefined; числа и флаги нужно преобразовать.
  • Проверка через Zod при запуске превращает забытую переменную в понятную ошибку старта, а не в падение на первом запросе.
  • В Git отправляется только .env.example без настоящих секретов.
  • На сервере и в CI переменные задаются через защищённые настройки окружения, а не файлом в репозитории.

Мини-шпаргалка

  • .env хранится только локально.
  • .env.example показывает нужные переменные без секретов.
  • Значения process.env считаются строками или undefined.
  • Zod преобразует и проверяет конфигурацию при старте.
  • Команды проекта должны одинаково работать локально и на сервере.

Документация

Node.js: Environment variables, dotenv, Zod: Basics, Zod: API.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам