Gizli Bilgileri Yönetme ve Ortam Değişkenleri

Bir React uygulamasında ortam değişkenleri iki sınıfa ayrılır: sunucu tarafı (tarayıcıya asla gönderilmez) ve istemci tarafı (JavaScript paketine gömülür). Değişkenlerinizin hangi sınıfa ait olduğunu anlamak, gizli bilgi yönetiminin ilk adımıdır; çünkü istemci tarafı değişkenleri paket dağıtıldıktan sonra fiilen herkese açıktır.

Vite projelerinde yalnızca VITE_ önekiyle başlayan değişkenler istemci paketine dahil edilir. VITE_PUBLIC_API_URL=https://api.example.com, tarayıcı kodunda import.meta.env.VITE_PUBLIC_API_URL aracılığıyla kullanılabilir. Diğer tüm değişkenler derleme zamanında paketten çıkarılır ve yalnızca sunucu tarafında kalır.

Next.js'te NEXT_PUBLIC_ öneki, bir değişkeni tarayıcıdaki JavaScript'e açar. NEXT_PUBLIC_ANALYTICS_ID=UA-123, istemci paketine gömülür. Öneki olmayan değişkenlere (örneğin DATABASE_URL) yalnızca sunucu tarafındaki koddan (Sunucu Bileşenleri, API rotaları, Sunucu Eylemleri) erişilebilir ve bu değişkenler tarayıcıya asla gönderilmez.

Öneki olmayan bir değişken, yanlışlıkla serileştirilirse yine erişilebilir hâle gelir. Örneğin bir Sunucu Bileşeni, yapılandırmasının tamamını bir İstemci Bileşenine özellik olarak geçirirse ve bu yapılandırma DATABASE_URL içerirse, bu gizli bilgi tarayıcıya gönderilen HTML'de görünür. Özelliklerin dikkatle aktarılması ve serileştirme denetimi bunu önler.

Aşağıdakiler istemci paketinde asla bulunmamalıdır: veritabanı bağlantı dizeleri ve parolaları, üçüncü taraf API gizli anahtarları (Stripe gizli anahtarı, OpenAI API anahtarı), özel RSA/EC anahtarları, JWT imzalama gizli bilgileri ve dahili hizmet kimlik doğrulama belirteçleri. Bunlardan herhangi biri bir API çağrısı için gerekiyorsa, bu çağrıyı bir sunucu uç noktası üzerinden yönlendiriniz.

Ön Uç için Arka Uç (BFF) deseni, React uygulamasıyla hassas harici hizmetler arasına ince bir sunucu katmanı yerleştirir. İstemci /api/stripe/charge çağrısını yapar, BFF sunucusu Stripe gizli anahtarını ekleyip Stripe API'sini çağırır ve BFF yalnızca gerekli yanıt verilerini döndürür. Gizli bilgiler kalıcı olarak sunucuda kalır.

dotenv-vault, .env dosyanızı şifreler ve düz metin gizli bilgileri sürüm denetimine göndermeden ortamlar arasında güvenli paylaşım ve dağıtım yapmanıza olanak tanır. Üretim için alternatifler arasında HashiCorp Vault (kurumsal), AWS Parameter Store (SSM) ve GCP Secret Manager bulunur — bunların tümü gizli bilgileri derleme zamanında değil, çalışma zamanında API üzerinden alır.

CI/CD platformları (GitHub Actions, GitLab CI), derlemeler sırasında ortam değişkenleri olarak erişilebilen şifrelenmiş gizli bilgi depolaması sunar. Gizli bilgileri GitHub Secrets'ta saklayınız ve iş akışlarında ${{ secrets.STRIPE_SECRET_KEY }} biçiminde başvurunuz. Gizli bilgiler günlüklerde maskelenir ve oluşturulan derleme çıktısına asla dahil edilmez.

Next.js ve Vite birden çok .env dosyasını destekler: .env (tüm ortamlar), .env.local (Git tarafından yok sayılan yerel geçersiz kılmalar), .env.development, .env.production. Yerel dosya, paylaşılan dosyadaki değerleri geçersiz kılarak diğer ortamları etkilemeden geliştiriciye özel yapılandırma yapılmasını sağlar.

Derlemeden sonra, yanlışlıkla açığa çıkan gizli bilgileri bulmak için JavaScript paketini denetleyiniz. grep -r "password|secret|api_key" dist/ komutunu çalıştırınız veya derlenmiş dosyalarda strings çözümlemesi gibi özel bir araç kullanınız. Yanlışlıkla dahil edilen bazı gizli bilgiler biçimlerinden (UUID'ler, base64 dizeleri veya sk_live_ gibi anahtar öneklerinden) kolayca tanınabilir.

Her ortam ve her hizmet yalnızca ihtiyaç duyduğu gizli bilgilere erişebilmelidir. React istemcisinin hiçbir gizli bilgiye ihtiyacı yoktur — yalnızca herkese açık tanımlayıcılar almalıdır. BFF sunucusu yalnızca çağırdığı API'ler için gereken gizli bilgilere ihtiyaç duyar. Geliştirme ortamları, izinleri ve harcama sınırları kısıtlı üretim dışı API anahtarları kullanmalıdır.

Vite, değişkenleri tarayıcı paketine açmak için VITE_ önekini; Next.js ise NEXT_PUBLIC_ önekini kullanır. Diğer tüm değişkenler yalnızca sunucu tarafındadır. Veritabanı parolalarını, API gizli anahtarlarını veya JWT imzalama gizli bilgilerini istemci koduna asla dahil etmeyiniz. Hassas API çağrılarını vekil olarak yönlendirmek için BFF desenini kullanınız. Üretimde gizli bilgi yönetimi için dotenv-vault, AWS Parameter Store veya GitHub Secrets kullanınız. Yanlışlıkla açığa çıkan gizli bilgiler için derlenmiş paketleri denetleyiniz.