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

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

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

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

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

هذا يحمل 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 لترقية الإصدارات المبنية في بيئة واحدة إلى بيئة أخرى، أو إذا قمت ببناء ونشر صورة 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)

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

بشكل عام، هناك حاجة إلى ملف .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

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

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