Ortam değişkenleri

Yapılandırma Koddan Ayrılır

Uygulamanız yerelde, önizleme ortamında ve canlıda çalışır. Kod her yerde aynıdır; değişen şey veritabanı adresi, API anahtarı, log seviyesi gibi değerlerdir. Bunlara yapılandırma (config) denir.

Heroku'nun 2011'de yayımladığı Twelve-Factor App ilkeleri bu ayrımı net koyar: yapılandırma koda sabit olarak yazılmaz, ortam değişkenlerinde tutulur. İlkenin pratik testi şudur: kod tabanını bu an açık kaynak yapsanız hiçbir kimlik bilgisi sızar mı?¹

Ortam değişkeni her işletim sisteminde ve dilde aynı şekilde çalışır. Kodu değiştirmeden ortamdan ortama değişir ve bir yapılandırma dosyası gibi yanlışlıkla depoya girmez.¹

.env Dosyaları

Next.js .env* dosyalarını kendiliğinden process.env'e yükler:²

# .env.local
DATABASE_URL=postgres://localhost:5432/orders
LOG_LEVEL=debug

Aynı değişken birden fazla yerde tanımlıysa ilk bulunan kazanır:²

next dev NODE_ENV'i development, diğer komutlar production yapar.² Yani canlı sunucuda platformun verdiği gerçek ortam değişkenleri, depodaki her dosyanın önündedir.

Hangi değişkenlerin gerektiğini ekip arkadaşlarınıza göstermek için değersiz bir şablon ekleyin ve yalnızca onu .gitignore'dan çıkarın:

# .env.example
APP_ENV=local
LOG_LEVEL=info
DATABASE_URL=

# .gitignore
.env*
!.env.example

Tarayıcıya Giden Değişkenler: NEXT_PUBLIC_

Varsayılan olarak ortam değişkenleri yalnızca sunucuda okunur. Bir değişkeni tarayıcıda kullanmak için adına NEXT_PUBLIC_ ön eki koyarsınız.²

Bu ön ek bir izin değil, bir kopyalama talimatıdır. Next.js next build sırasında process.env.NEXT_PUBLIC_ANALYTICS_ID geçen her yeri o anki değerle değiştirir ve değer JavaScript paketine gömülür:²

// Build sırasında "abc123" ile değiştirilir
const analyticsId = process.env.NEXT_PUBLIC_ANALYTICS_ID;

// Değiştirilmez: değişken adı dinamik
const name = "NEXT_PUBLIC_ANALYTICS_ID";
const value = process.env[name];

İki sonucu var:

1. Secret'a asla NEXT_PUBLIC_ vermeyin. Değer, siteyi açan herkesin indirdiği dosyadadır.

2. Build'den sonra değişmez. Aynı build'i önizlemeden canlıya taşırsanız ya da tek bir Docker imajını birden fazla ortamda çalıştırırsanız, NEXT_PUBLIC_ değerleri build anındaki halinde donar.²

Çalışma Zamanında Okumak

NEXT_PUBLIC_ olmayan bir değişken sunucuda okunur ama ne zaman okunduğu önemlidir. Build sırasında önceden çizilen (prerender) bir sayfa değişkeni build anında okur ve sonucu saklar.

Değerin istek anında okunması için önce connection()'ı bekleyin. Bu, Next.js'e o kısmın isteğe bağlı olduğunu söyler:²

// app/api/health/route.ts
import { connection } from "next/server";

export async function GET() {
  await connection();
  return Response.json({ version: process.env.APP_VERSION });
}

cookies(), headers() gibi istek anı API'leri de aynı etkiyi yapar. Next.js dokümanı bu yolun faydasını şöyle söyler: tek bir Docker imajı farklı değerlerle ortamdan ortama taşınabilir.²³ Twelve-Factor'ın "build, release, run" ayrımı da budur: bir kez build alınır, her ortamın yapılandırmasıyla birleşip çalıştırılır.⁴

Doğrulamak: Açılışta Hata Ver

process.env.LOG_LEVEL her zaman string | undefined tipindedir. Yazım hatası, eksik değer ya da "150" gibi geçersiz bir sayı ilk kullanıldığı ana kadar fark edilmez; o an da genellikle gece yarısı bir kullanıcının isteğidir.

Değişkenleri tek bir yerde Zod ile doğrulayın (bkz. Zod şeması ve doğrulama):

// lib/env.ts
import "server-only";
import { z } from "zod";

const envSchema = z.object({
  APP_ENV: z.enum(["local", "preview", "production"]).default("local"),
  APP_VERSION: z.string().min(1).default("dev"),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
  ORDER_SUMMARY_ROLLOUT: z.coerce.number().int().min(0).max(100).default(0),
});

export type Env = z.infer<typeof envSchema>;

let cached: Env | undefined;

export function getEnv(): Env {
  if (cached) return cached;

  const result = envSchema.safeParse(process.env);
  if (!result.success) {
    const problems = result.error.issues
      .map((issue) => `- ${issue.path.join(".")}: ${issue.message}`)
      .join("\n");
    throw new Error(`Geçersiz ortam değişkenleri:\n${problems}`);
  }

  cached = result.data;
  return cached;
}

• z.coerce.number() metni sayıya çevirir. Ortam değişkenleri her zaman metindir.⁵

• default isteğe bağlı değerleri tanımlar. Zorunlu bir secret için varsayılan vermeyin; eksikse hata versin.

• "server-only" bu dosya bir Client Component'e import edilirse build'i durdurur (bkz. Server ve Client Components).

Doğrulamayı ilk istekte değil, sunucu açılırken çalıştırın. Next.js'in register fonksiyonu sunucu başlarken bir kez çalışır:⁶

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation-node");
  }
}

// instrumentation-node.ts
import { getEnv } from "./lib/env";

try {
  getEnv();
} catch (error) {
  console.error(error instanceof Error ? error.message : error);
  process.exit(1);
}

process.exit Edge çalışma ortamında yoktur. Node.js'e özgü kodu ayrı bir dosyaya koyup NEXT_RUNTIME kontrolüyle import etmek, dokümanın önerdiği yoldur ve build uyarısını önler.⁶ Sonuç:

$ ORDER_SUMMARY_ROLLOUT=150 npm start

Geçersiz ortam değişkenleri:
- ORDER_SUMMARY_ROLLOUT: Too big: expected number to be <=100

Sunucu hiç trafik almadan kapanır. Bir konteyner platformu yeni sürümü sağlıksız sayar ve eski sürümü çalıştırmaya devam eder.

Ortam Başına Değerler

NODE_ENV yalnızca development, production ya da test olabilir.² Önizleme ortamı da production build'idir. "Hangi ortamdayım?" sorusu için APP_ENV gibi kendi değişkeninizi tanımlayın.

Twelve-Factor ise değerleri staging, qa gibi adlandırılmış gruplara toplamaya karşı uyarır: ortam sayısı arttıkça gruplar çoğalır ve yönetmek zorlaşır. Her değişken bağımsız bir ayardır ve her deploy için ayrı yönetilir.¹ APP_ENV'i davranışı açıp kapamak için değil, loglarda ve hata kayıtlarında ortamı ayırmak için kullanın.

Değerleri nereden verirsiniz?

Secret'ları Korumak

OWASP'ın secret yönetimi rehberi secret'ları merkezi bir yerde tutmayı ve her birini bir yaşam döngüsüyle yönetmeyi önerir: oluşturma, düzenli döndürme (rotation), iptal ve süre dolumu. Elle yapılan döndürme hataya açık olduğu için mümkünse otomatikleştirilmelidir.⁷

Kendin Dene

• Projenize lib/env.ts ekleyin. Bir değişkene geçersiz değer verip sunucunun açılışta kapandığını görün.

• NEXT_PUBLIC_ ile bir değer tanımlayın, next build alın ve .next/static içinde değeri arayın.

• Statik bir sayfada process.env okuyun, build sonrası değeri değiştirip sunucuyu yeniden başlatın. Değer değişti mi? connection() ekleyip tekrar deneyin.

• Bir .env.example yazın ve .gitignore'u yalnızca onu izleyecek şekilde düzenleyin.

Detaylı Öğrenmek İçin

• Resmi doküman: Next.js, "Environment Variables"; yükleme sırası, NEXT_PUBLIC_ ve test ortamı.²

• Yazı: Heroku, "The Twelve-Factor App: Config"; yapılandırmayı koddan ayırmanın gerekçesi.¹

• Rehber: OWASP, "Secrets Management Cheat Sheet"; secret'ların yaşam döngüsü.⁷