كيفية استخدام متغيرات البيئة في Next.js

يأتي Next.js مع دعم مدمج لمتغيرات البيئة، مما يسمح لك بما يلي:

• استخدام .env لتحميل متغيرات البيئة
• حزم متغيرات البيئة للمتصفح عن طريق البادئة NEXT_PUBLIC_

تحذير: يضمن قالب create-next-app الافتراضي إضافة جميع ملفات .env إلى .gitignore. لا تريد عادةً إضافة هذه الملفات إلى مستودعك.

تحميل متغيرات البيئة

يدعم Next.js تحميل متغيرات البيئة من ملفات .env* إلى process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

ملاحظة: يدعم Next.js أيضًا متغيرات متعددة الأسطر داخل ملفات .env*:

# .env

# يمكنك الكتابة مع فواصل الأسطر
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# أو مع `\n` داخل علامات اقتباس مزدوجة
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

ملاحظة: إذا كنت تستخدم مجلد /src، يرجى ملاحظة أن Next.js سيحمل ملفات .env فقط من المجلد الرئيسي و ليس من مجلد /src. هذا يحمل process.env.DB_HOST، process.env.DB_USER، و process.env.DB_PASS إلى بيئة Node.js تلقائيًا مما يسمح لك باستخدامها في معالجات المسار.

على سبيل المثال:

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

تحميل متغيرات البيئة باستخدام @next/env

إذا كنت بحاجة إلى تحميل متغيرات البيئة خارج وقت تشغيل Next.js، مثل ملف تكوين جذر لـ ORM أو أداة اختبار، يمكنك استخدام حزمة @next/env.

هذه الحزمة تستخدم داخليًا بواسطة Next.js لتحميل متغيرات البيئة من ملفات .env*.

لاستخدامها، قم بتثبيت الحزمة واستخدم دالة loadEnvConfig لتحميل متغيرات البيئة:

npm install @next/env

import { loadEnvConfig } from '@next/env'

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

import { loadEnvConfig } from '@next/env'

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

ثم، يمكنك استيراد التكوين حيثما تحتاج. على سبيل المثال:

import './envConfig.ts'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

import './envConfig.js'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
})

الإشارة إلى متغيرات أخرى

سيقوم Next.js تلقائيًا بتوسيع المتغيرات التي تستخدم $ للإشارة إلى متغيرات أخرى مثل $VARIABLE داخل ملفات .env*. هذا يسمح لك بالإشارة إلى أسرار أخرى. على سبيل المثال:

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

في المثال أعلاه، سيتم تعيين process.env.TWITTER_URL إلى https://x.com/nextjs.

جيد أن تعرف: إذا كنت بحاجة إلى استخدام متغير مع $ في القيمة الفعلية، يجب تهريبه مثل \$.

حزم متغيرات البيئة للمتصفح

متغيرات البيئة غير NEXT_PUBLIC_ متاحة فقط في بيئة Node.js، مما يعني أنها غير متاحة للمتصفح (يعمل العميل في بيئة مختلفة).

لجعل قيمة متغير البيئة متاحة في المتصفح، يمكن لـ Next.js "تضمين" القيمة، في وقت البناء، في حزمة js التي يتم تسليمها إلى العميل، واستبدال جميع الإشارات إلى process.env.[variable] بقيمة ثابتة. لإخباره بفعل ذلك، ما عليك سوى إضافة البادئة NEXT_PUBLIC_ للمتغير. على سبيل المثال:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

سيخبر هذا Next.js باستبدال جميع الإشارات إلى process.env.NEXT_PUBLIC_ANALYTICS_ID في بيئة Node.js بالقيمة من البيئة التي تقوم فيها بتشغيل next build، مما يسمح لك باستخدامها في أي مكان في الكود الخاص بك. سيتم تضمينها في أي JavaScript يتم إرساله إلى المتصفح.

ملاحظة: بعد البناء، لن يستجيب تطبيقك للتغييرات في متغيرات البيئة هذه. على سبيل المثال، إذا كنت تستخدم خط أنابيب Heroku لترقية slugs المبنية في بيئة إلى بيئة أخرى، أو إذا قمت ببناء ونشر صورة Docker واحدة إلى بيئات متعددة، سيتم تجميد جميع متغيرات NEXT_PUBLIC_ بالقيمة التي تم تقييمها في وقت البناء، لذا يجب تعيين هذه القيم بشكل مناسب عند بناء المشروع. إذا كنت بحاجة إلى الوصول إلى قيم بيئة التشغيل، سيتعين عليك إعداد API خاص بك لتوفيرها للعميل (إما عند الطلب أو أثناء التهيئة).

import setupAnalyticsService from '../lib/my-analytics-service'

// يمكن استخدام 'NEXT_PUBLIC_ANALYTICS_ID' هنا لأنه مسبوق بـ 'NEXT_PUBLIC_'.
// سيتم تحويله في وقت البناء إلى `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

لاحظ أن عمليات البحث الديناميكية لن يتم تضمينها، مثل:

// لن يتم تضمين هذا لأنه يستخدم متغير
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// لن يتم تضمين هذا لأنه يستخدم متغير
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

متغيرات بيئة التشغيل

يمكن لـ Next.js دعم كل من متغيرات بيئة البناء وبيئة التشغيل.

بشكل افتراضي، متغيرات البيئة متاحة فقط على الخادم. لكشف متغير بيئة للمتصفح، يجب أن يكون مسبوقًا بـ NEXT_PUBLIC_. ومع ذلك، سيتم تضمين متغيرات البيئة العامة هذه في حزمة JavaScript أثناء next build.

يمكنك قراءة متغيرات البيئة بأمان على الخادم أثناء العرض الديناميكي:

import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // ملفات تعريف الارتباط، الرؤوس، وواجهات برمجة التطبيقات الديناميكية الأخرى
  // ستعمل أيضًا على العرض الديناميكي، مما يعني
  // أن متغير البيئة هذا يتم تقييمه في وقت التشغيل
  const value = process.env.MY_VALUE
  // ...
}

import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // ملفات تعريف الارتباط، الرؤوس، وواجهات برمجة التطبيقات الديناميكية الأخرى
  // ستعمل أيضًا على العرض الديناميكي، مما يعني
  // أن متغير البيئة هذا يتم تقييمه في وقت التشغيل
  const value = process.env.MY_VALUE
  // ...
}

هذا يسمح لك باستخدام صورة Docker واحدة يمكن ترقيتها عبر بيئات متعددة بقيم مختلفة.

جيد أن تعرف:

• يمكنك تشغيل الكود عند بدء تشغيل الخادم باستخدام دالة register.
• لا نوصي باستخدام خيار runtimeConfig، لأنه لا يعمل مع وضع الإخراج المستقل. بدلاً من ذلك، نوصي بتبني موجه التطبيق تدريجيًا إذا كنت بحاجة إلى هذه الميزة.

متغيرات بيئة الاختبار

بالإضافة إلى بيئات development و production، هناك خيار ثالث متاح: test. بنفس الطريقة التي يمكنك فيها تعيين قيم افتراضية لبيئات التطوير أو الإنتاج، يمكنك فعل ذلك مع ملف .env.test لبيئة testing (على الرغم من أن هذا ليس شائعًا مثل السابقين). لن يقوم Next.js بتحميل متغيرات البيئة من .env.development أو .env.production في بيئة testing.

هذا مفيد عند تشغيل الاختبارات باستخدام أدوات مثل jest أو cypress حيث تحتاج إلى تعيين متغيرات بيئة محددة فقط لأغراض الاختبار. سيتم تحميل القيم الافتراضية للاختبار إذا تم تعيين NODE_ENV إلى test، على الرغم من أنك عادةً لا تحتاج إلى فعل هذا يدويًا حيث ستقوم أدوات الاختبار بذلك نيابةً عنك.

هناك فرق صغير بين بيئة test، وكل من development و production تحتاج إلى تذكره: لن يتم تحميل .env.local، حيث تتوقع أن تنتج الاختبارات نفس النتائج للجميع. بهذه الطريقة، كل تنفيذ اختبار سيستخدم نفس إعدادات البيئة الافتراضية عبر تنفيذات مختلفة بتجاهل .env.local الخاص بك (الذي يُقصد به تجاوز المجموعة الافتراضية).

جيد أن تعرف: مثل متغيرات البيئة الافتراضية، يجب تضمين ملف .env.test في مستودعك، ولكن لا يجب تضمين .env.test.local، حيث أن .env*.local يُقصد بها أن يتم تجاهلها عبر .gitignore.

أثناء تشغيل اختبارات الوحدة، يمكنك التأكد من تحميل متغيرات البيئة بنفس الطريقة التي يفعلها Next.js عن طريق الاستفادة من دالة loadEnvConfig من حزمة @next/env.

// يمكن استخدام ما يلي في ملف إعداد عام لـ Jest أو ما شابه لإعداد الاختبار الخاص بك
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 (لا يتم التحقق منه عندما تكون NODE_ENV هي test.)
4. .env.$(NODE_ENV)
5. .env

على سبيل المثال، إذا كانت NODE_ENV هي development وقمت بتعريف متغير في كل من .env.development.local و .env، سيتم استخدام القيمة في .env.development.local.

جيد أن تعرف: القيم المسموح بها لـ NODE_ENV هي production، development و test.

جيد أن تعرف

• إذا كنت تستخدم مجلد /src، يجب أن تبقى ملفات .env.* في جذر مشروعك.
• إذا كان متغير البيئة NODE_ENV غير معين، يقوم Next.js تلقائيًا بتعيين development عند تشغيل أمر next dev، أو production لجميع الأوامر الأخرى.

سجل الإصدارات