Как работают переменные окружения в Next.js?

Question

Accepted Answer

Next.js загружает переменные окружения из файлов `.env` с важным правилом безопасности: переменные **доступны только на сервере по умолчанию**, и только те, которые имеют префикс `NEXT_PUBLIC_`, предоставляются браузеру.

## Файлы

```text
.env                # loaded in all environments
.env.local          # local overrides — GITIGNORED (put secrets here)
.env.development    # only in `next dev`
.env.production     # only in production builds
```

## Критическое правило префикса

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com  # exposed to the browser
```

```tsx
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL;          // ✅ works on the server

// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ works
const secret = process.env.DATABASE_URL;      // ❌ undefined in the browser
```

Это правило префикса — это **функция безопасности**: оно предотвращает случайную передачу паролей базы данных или секретов API клиенту. Переменная без префикса просто не существует в бандлах браузера.

## Как встраиваются значения NEXT_PUBLIC

```text
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
```

Поскольку они встроены во время сборки, изменение значения `NEXT_PUBLIC_` требует **пересборки** — и вы никогда не должны помещать настоящие секреты за префиксом (они будут видны в бандле для всех).

## Лучшие практики

```text
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
```

## Почему это важно

Модель «только на сервере по умолчанию» с опцией `NEXT_PUBLIC_` — это защита Next.js от утечки секретов клиенту — распространённая и серьёзная ошибка.

Понимание того, какие переменные попадают в браузер, что публичные значения встроены во время сборки и где хранить секреты (игнорируемый `.env.local`), необходимо как для функциональности, так и для безопасности.