Next.js'te ortam değişkenleri nasıl çalışır?

Question

Accepted Answer

Next.js, `.env` dosyalarından ortam değişkenlerini önemli bir güvenlik kuralıyla yükler: değişkenler **varsayılan olarak yalnızca sunucu için**'dir ve yalnızca `NEXT_PUBLIC_` önekine sahip olanlar tarayıcıya sunulur.

## Dosyalar

```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
```

## Kritik ön ek kuralı

```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
```

Bu ön ek kuralı bir **güvenlik özelliği**'dir: veritabanı parolaları veya API sırlarını yanlışlıkla istemciye göndermekten sizi korur. Ön eki olmayan bir değişken tarayıcı paketlerinde basitçe mevcut değildir.

## NEXT_PUBLIC_ değerleri nasıl gömülür

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

Bunlar derleme zamanında satır içine alındığından, bir `NEXT_PUBLIC_` değerini değiştirmek **yeniden derleme** gerektirir — ve asıl sırları ön ekin arkasına asla koymayınız (pakette herkese görünür olurdu).

## En iyi uygulamalar

```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)
```

## Neden önemli

`NEXT_PUBLIC_` katılımıyla sunucu yalnızca varsayılan modeli, sırları istemciye sızdırmaktan koruyan Next.js'in güvence sistemidir — yaygın ve ciddi bir hata.

Hangi değişkenlerin tarayıcıya ulaştığını, genel değerlerin derleme zamanında satır içine alındığını ve sırların nerede saklanacağını (gitignore edilmiş `.env.local`) anlamak hem işlevsellik hem de güvenlik için gereklidir.