استفاده از متغیرهای محیطی در Next.js – بارگذاری امن، دسترسی در مرورگر و مدیریت در زمان اجرا

بارگذاری متغیرهای محیطی

Next.js به‌صورت خودکار متغیرهای محیطی را از فایل‌های .env* بارگذاری کرده و در process.env قرار می‌دهد. مثال:

# .env
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

متغیرها در محیط Node.js قابل استفاده هستند، مانند در Route Handlerها:

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

پشتیبانی از متغیرهای چندخطی

می‌توانید متغیرهایی مانند کلیدهای خصوصی را با line break یا \n تعریف کنید:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----"

بارگذاری خارج از محیط Next.js با @next/env

برای بارگذاری متغیرها در فایل‌هایی خارج از runtime، از پکیج @next/env استفاده کنید:

import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

ارجاع به متغیرهای دیگر

می‌توانید از $ برای ارجاع به متغیر دیگر استفاده کنید:

# .env
TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

برای استفاده از $ در مقدار واقعی، از \$ استفاده کنید.

دسترسی در مرورگر با NEXT_PUBLIC_

برای در دسترس بودن متغیر در مرورگر، باید با NEXT_PUBLIC_ شروع شود:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

در زمان build، مقدار در فایل‌های جاوااسکریپت inlined می‌شود:

setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

توجه: ارجاع‌های پویا مانند process.env[varName] inlined نمی‌شوند.

متغیرهای زمان اجرا

در رندرینگ پویا، می‌توانید متغیرها را در زمان اجرا بخوانید:

export default async function Component() {
  await connection()
  const value = process.env.MY_VALUE
}

این روش برای استفاده از یک Docker image در چند محیط مناسب است.

متغیرهای محیطی در تست

برای محیط تست، از فایل .env.test استفاده کنید. فایل .env.local در تست بارگذاری نمی‌شود تا نتایج تست یکسان باقی بمانند.

برای بارگذاری مشابه Next.js در تست‌ها:

import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

ترتیب بارگذاری متغیرها

متغیرها به ترتیب زیر بررسی می‌شوند:

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (در تست بارگذاری نمی‌شود)
4. .env.$(NODE_ENV)
5. .env

مثلاً اگر NODE_ENV برابر با development باشد، مقدار موجود در .env.development.local اولویت دارد.

نکات مهم

• فایل‌های .env* باید در ریشه پروژه باشند، نه در پوشه