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

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

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

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

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

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

# .env.local

# يمكنك الكتابة مع فواصل الأسطر
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.js تلقائيًا بتوسيع المتغيرات التي تستخدم $ للإشارة إلى متغيرات أخرى مثل $VARIABLE داخل ملفات .env*. هذا يسمح لك بالإشارة إلى أسرار أخرى. على سبيل المثال:

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

في المثال أعلاه، سيتم تعيين process.env.TWITTER_URL إلى https://twitter.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.

لقراءة متغيرات بيئة التشغيل، نوصي باستخدام getServerSideProps أو اعتماد موجه التطبيق تدريجيًا. مع موجه التطبيق، يمكننا قراءة متغيرات البيئة بأمان على الخادم أثناء التصيير الديناميكي. هذا يسمح لك باستخدام صورة Docker واحدة يمكن ترقيتها عبر بيئات متعددة بقيم مختلفة.

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies()، headers()، وغيرها من الدوال الديناميكية
  // ستختار أيضًا التصيير الديناميكي، مما يعني
  // أن متغير البيئة هذا يتم تقييمه في وقت التشغيل
  const value = process.env.MY_VALUE
  // ...
}

معلومة مفيدة:

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

متغيرات البيئة الافتراضية

بشكل عام، هناك حاجة إلى ملف .env.local واحد فقط. ومع ذلك، قد ترغب أحيانًا في إضافة بعض الإعدادات الافتراضية لبيئة التطوير (next dev) أو الإنتاج (next start).

يسمح لك Next.js بتعيين الإعدادات الافتراضية في .env (جميع البيئات)، .env.development (بيئة التطوير)، و .env.production (بيئة الإنتاج).

.env.local دائمًا ما يتجاوز الإعدادات الافتراضية.

معلومة مفيدة: يجب تضمين ملفات .env، .env.development، و .env.production في مستودعك لأنها تحدد الإعدادات الافتراضية. يجب إضافة .env*.local إلى .gitignore، لأن هذه الملفات مخصصة لتجاهلها. .env.local هو المكان الذي يمكن تخزين الأسرار فيه.

متغيرات البيئة على Vercel

عند نشر تطبيق Next.js الخاص بك على Vercel، يمكن تكوين متغيرات البيئة في إعدادات المشروع.

يجب تكوين جميع أنواع متغيرات البيئة هناك. حتى متغيرات البيئة المستخدمة في التطوير - والتي يمكن تنزيلها على جهازك المحلي لاحقًا.

إذا قمت بتكوين متغيرات بيئة التطوير، يمكنك سحبها إلى .env.local للاستخدام على جهازك المحلي باستخدام الأمر التالي:

vercel env pull .env.local

معلومة مفيدة: عند نشر تطبيق Next.js الخاص بك على Vercel، لن تكون متغيرات البيئة في ملفات .env* متاحة لـ Edge Runtime، إلا إذا كانت أسمائها مبدوءة بـ NEXT_PUBLIC_. نوصي بشدة بإدارة متغيرات البيئة في إعدادات المشروع بدلاً من ذلك، حيث تكون جميع متغيرات البيئة متاحة.

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

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

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

هناك فرق صغير بين بيئة الاختبار، وكل من التطوير والإنتاج يجب أن تضع في اعتبارك: لن يتم تحميل .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 لجميع الأوامر الأخرى.

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