Environment Variables

Next.js, aşağıdakileri yapmanıza olanak tanıyan ortam değişkenleri için yerleşik destekle birlikte gelir:

• Ortam değişkenlerini yüklemek için .env.local adresini kullanın
• ile önekleyerek tarayıcı için ortam değişkenlerini paketleyin NEXT_PUBLIC_

Loading Environment Variables

Next.js, ortam değişkenlerini .env.local adresinden process.env adresine yüklemek için yerleşik desteğe sahiptir.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Bu, process.env.DB_HOST, process.env.DB_USER ve process.env.DB_PASS adreslerini Node.js ortamına otomatik olarak yükler ve bunları Next.js veri getirme yöntemlerinde ve API rotalarında kullanmanıza olanak tanır.

Örneğin, aşağıdakileri kullanarak getStaticProps:

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

Referencing Other Variables

Next.js, .env* dosyalarınızın içinde $VARIABLE gibi diğer değişkenlere referans vermek için $ kullanan değişkenleri otomatik olarak genişletecektir. Bu, diğer sırlara referans vermenizi sağlar. Örneğin:

TWITTER_USER=nextjs
TWITTER_URL=https://twitter.com/$TWITTER_USER

Yukarıdaki örnekte, process.env.TWITTER_URL adresi https://twitter.com/nextjs olarak ayarlanacaktır.

Bilmekte fayda var: Gerçek değerde $ ile değişken kullanmanız gerekiyorsa, örneğin \$ gibi öncelenmesi gerekir.

Bundling Environment Variables for the Browser

Non-NEXT_PUBLIC_ ortam değişkenleri yalnızca Node.js ortamında kullanılabilir, yani tarayıcı tarafından erişilemezler (istemci farklı bir ortamda çalışır).

Bir ortam değişkeninin değerini tarayıcıda erişilebilir kılmak için Next.js, derleme sırasında istemciye teslim edilen js paketine bir değer "ekleyebilir" ve process.env.[variable] adresine yapılan tüm referansları sabit kodlu bir değerle değiştirebilir. Bunu yapmasını söylemek için değişkenin önüne NEXT_PUBLIC_ eklemeniz yeterlidir. Örneğin:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Bu, Next.js'ye Node.js ortamındaki process.env.NEXT_PUBLIC_ANALYTICS_ID adresine yapılan tüm referansları next build adresini çalıştırdığınız ortamdaki değerle değiştirmesini söyleyerek kodunuzun herhangi bir yerinde kullanmanıza olanak tanır. Tarayıcıya gönderilen tüm JavaScript'lerde satır içi olarak yer alacaktır.

Not: Oluşturulduktan sonra, uygulamanız artık bu ortam değişkenlerindeki değişikliklere yanıt vermeyecektir. Örneğin, bir ortamda oluşturulan slug'ları başka bir ortama tanıtmak için bir Heroku boru hattı kullanıyorsanız veya tek bir Docker görüntüsü oluşturup birden fazla ortama dağıtıyorsanız, tüm NEXT_PUBLIC_ değişkenleri derleme zamanında değerlendirilen değerle dondurulacaktır, bu nedenle proje oluşturulduğunda bu değerlerin uygun şekilde ayarlanması gerekir. Çalışma zamanı ortam değerlerine erişmeniz gerekiyorsa, bunları istemciye sağlamak için kendi API'nizi kurmanız gerekir (talep üzerine veya başlatma sırasında).

import setupAnalyticsService from '../lib/my-analytics-service'
 
// 'NEXT_PUBLIC_ANALYTICS_ID' can be used here as it's prefixed by 'NEXT_PUBLIC_'.
// It will be transformed at build time to `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
 
function HomePage() {
  return <h1>Hello World</h1>
}
 
export default HomePage

Aşağıdaki gibi dinamik aramaların satır içi yapılmayacağını unutmayın:

// This will NOT be inlined, because it uses a variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
 
// This will NOT be inlined, because it uses a variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

Runtime Environment Variables

Next.js hem derleme zamanı hem de çalışma zamanı ortam değişkenlerini destekleyebilir.

Varsayılan olarak, ortam değişkenleri yalnızca sunucuda kullanılabilir. Bir ortam değişkenini tarayıcıya göstermek için, önüne NEXT_PUBLIC_ eklenmelidir. Ancak, bu genel ortam değişkenleri next build sırasında JavaScript paketinde satır içine alınacaktır.

Çalışma zamanı ortam değişkenlerini okumak için getServerSideProps adresini kullanmanızı veya App Router'ı aşamalı olarak benimsemenizi öneririz. App Router ile dinamik işleme sırasında sunucudaki ortam değişkenlerini güvenle okuyabiliriz. Bu, farklı değerlere sahip birden fazla ortam aracılığıyla yükseltilebilen tekil bir Docker görüntüsü kullanmanıza olanak tanır.

import { unstable_noStore as noStore } from 'next/cache'
 
export default function Component() {
  noStore()
  // cookies(), headers(), and other dynamic functions
  // will also opt into dynamic rendering, making
  // this env variable is evaluated at runtime
  const value = process.env.MY_VALUE
  // ...
}

Bildiğim iyi oldu:

• register işlevini kullanarak sunucu başlangıcında kod çalıştırabilirsiniz.
• Bağımsız çıktı modunda çalışmadığı için runtimeConfig seçeneğinin kullanılmasını önermiyoruz. Bunun yerine, App Router'ı aşamalı olarak benimsemenizi öneririz.

Default Environment Variables

Genel olarak sadece bir .env.local dosyası gereklidir. Ancak, bazen development (next dev) veya production (next start) ortamı için bazı varsayılanlar eklemek isteyebilirsiniz.

Next.js, .env (tüm ortamlar), .env.development (geliştirme ortamı) ve .env.production (üretim ortamı) varsayılanlarını ayarlamanıza olanak tanır.

.env.local her zaman ayarlanan varsayılanları geçersiz kılar.

Bilmekte fayda var: .env, .env.development ve .env.production dosyaları varsayılanları tanımladıkları için deponuza dahil edilmelidir. .env*.local, bu dosyaların göz ardı edilmesi amaçlandığı için .gitignore adresine eklenmelidir. .env.local, sırların saklanabileceği yerdir.

Environment Variables on Vercel

Next.js uygulamanızı Vercel adresine dağıtırken, Ortam Değişkenleri Proje Ayarları adresinden yapılandırılabilir.

Her tür Ortam Değişkeni burada yapılandırılmalıdır. Geliştirmede kullanılan Ortam Değişkenleri bile - daha sonra yerel cihazınıza indirilebilir.

Geliştirme Ortamı Değişkenlerini yapılandırdıysanız, aşağıdaki komutu kullanarak bunları yerel makinenizde kullanmak üzere bir .env.local içine çekebilirsiniz:

vercel env pull .env.local

Bilmekte fayda var: Next.js uygulamanızı Vercel adresine dağıtırken, .env* dosyalarındaki ortam değişkenleriniz, adlarının önüne NEXT_PUBLIC_ eklenmediği sürece Edge Runtime tarafından kullanılamayacaktır. Bunun yerine, ortam değişkenlerinizi tüm ortam değişkenlerinin mevcut olduğu Proje Ayarları adresinden yönetmenizi şiddetle tavsiye ederiz.

Test Environment Variables

development ve production ortamlarının dışında 3. bir seçenek daha mevcuttur: test. Geliştirme veya üretim ortamları için varsayılanları ayarlayabildiğiniz gibi, aynı şeyi testing ortamı için bir .env.test dosyasıyla da yapabilirsiniz (ancak bu önceki ikisi kadar yaygın değildir). Next.js, testing ortamındaki .env.development veya .env.production ortam değişkenlerini yüklemeyecektir.

Bu, yalnızca test amacıyla belirli ortam değişkenlerini ayarlamanız gereken jest veya cypress gibi araçlarla testler çalıştırırken kullanışlıdır. Test varsayılan değerleri NODE_ENV test olarak ayarlanırsa yüklenecektir, ancak test araçları bunu sizin için ele alacağından genellikle bunu manuel olarak yapmanız gerekmez.

test ortamı ile hem development hem de production arasında aklınızda bulundurmanız gereken küçük bir fark vardır: testlerin herkes için aynı sonuçları üretmesini beklediğiniz için .env.local yüklenmeyecektir. Bu şekilde, her test yürütmesi, .env.local adresinizi (varsayılan seti geçersiz kılmak için tasarlanmıştır) yok sayarak farklı yürütmelerde aynı env varsayılanlarını kullanacaktır.

Bilmenizde fayda var: Varsayılan Ortam Değişkenlerine benzer şekilde, .env.test dosyası deponuza dahil edilmelidir, ancak .env.test.local dahil edilmemelidir, çünkü .env*.local dosyasının .gitignore aracılığıyla göz ardı edilmesi amaçlanmıştır.

Birim testlerini çalıştırırken, @next/env paketindeki loadEnvConfig işlevinden yararlanarak ortam değişkenlerinizi Next.js'nin yaptığı gibi yüklediğinizden emin olabilirsiniz.

// The below can be used in a Jest global setup file or similar for your testing set-up
import { loadEnvConfig } from '@next/env'
 
export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Environment Variable Load Order

Ortam değişkenleri sırasıyla aşağıdaki yerlerde aranır ve değişken bulunduğunda durdurulur.

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local ( NODE_ENV test olduğunda kontrol edilmez.)
4. .env.$(NODE_ENV)
5. .env

Örneğin, NODE_ENV adresi development ise ve hem .env.development.local hem de .env adreslerinde bir değişken tanımlarsanız, .env.development.local adresindeki değer kullanılacaktır.

Bilmekte fayda var: NODE_ENV için izin verilen değerler production, development ve test şeklindedir.

Good to know

• Eğer bir /src dizini kullanıyorsanız, .env.* dosyaları projenizin kök dizininde kalmalıdır.
• NODE_ENV ortam değişkeni atanmamışsa, Next.js next dev komutunu çalıştırırken otomatik olarak development veya diğer tüm komutlar için production atar.

Version History