متغيرات البيئة Environment Variables في Next.js

تدعم 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 تلقائيًا مما يسمح لك باستخدام طرق Next.js في إحضار البيانات واستخدام واجهة التوجيه. إليك مثالًا باستخدام getStaticProps:

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

ملاحظة: لتُبقي الأمور الحساسة الموجودة فقط على الخادم محمية، تُستبدل متغيرات البيئة بالقيمة الصحيحة أثناء بناء التطبيق. يعني ذلك أن الكائن process.env ليس كائنًا معياريًا في JavaScript، ولن تكون قادرًا على تفكيك الكائن. لا بد من الإشارة إلى متغيرات البيئة كالتالي:

process.env.PUBLISHABLE_KEY;
// أو
const { PUBLISHABLE_KEY } = process.env;

ملاحظة: تُوسِّع Next.js تلقائيًا المتغيّر VAR$ ضمن ملف متغيرات البيئة ويساعدك ذلك في الإشارة إلى أمور محمية أخرى:

# .env
HOSTNAME=localhost
PORT=8080
HOST=http://$HOSTNAME:$PORT

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

# .env
A=abc

# "preabc" ستصبح قيمة المتغير 
WRONG=pre$A

# "pre$A" ستصبح قيمة المتغيّر 
CORRECT=pre\$A

ملاحظة: إن كنت تستخدم المجلّد src/ فلا بد من تنبيهك أن Next.js تحمّل الملفات من المجلد الأب فقط وليس من المجلد src/.

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

تُعد متغيرات البيئة متغيرات في بيئة Node.js وبالتالي لن تكون متاحة في بيئة المتصفح. ولكي تكشف متغيرات البيئة للمتصفح، لا بد من إضافة البادئة _NEXT_PUBLIC إلى المتغير. إليك مثالًا:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

يحمّل ذلك process.env.NEXT_PUBLIC_ANALYTICS_ID إلى بيئة عمل Node.js تلقائيًا مما يسمح باستخدامها في أي مكان من الشيفرة. ستُوضَّب هذه القيمة ضمن شيفرة JavaScript التي تُرسل إلى المتصفح نظرًا لوجود البادئة _NEXT_PUBLIC. تجري عملية التوضيب أثناء بناء التطبيق وبالتالي لابد أن تُضبط قيم جميع متغيرات البيئة التي تمتلك تلك البادئة قبل بناء المشروع.

// pages/index.js
import setupAnalyticsService from '../lib/my-analytics-service'

//NEXT_PUBLIC_ نظرًا لوجود البادئة NEXT_PUBLIC_ANALYTICS_ID يمكن استخدام 

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

اختبار متحولات البيئة في Next.js

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

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

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

ملاحظة: لا بد من وضع الملف env.test. في مستودعك وليس الملف env.test.local. لأننا ننوي تجاهل الملفاتenv*.local. في gitignore..

تأكد عندما تُجري اختبارات وحدة unit tests أن تُحمِّل متغيرات البيئة بالطريقة التقليدية من خلال الدالة loadEnvConfig الموجودة في الحزمة ‎@next/env.

// العام وبشكل مشابه لملف Jest يمكن استخدام هذه الشيفرة في ملف إعداد
// إعداد الاختبار الخاص بك
import { loadEnvConfig } from '@next/env'

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

ترتيب تحميل متغيرات البيئة في Next.js

وفقًا للبيئة التي تختارها (كما ضُبطت في NODE_ENV)، تُحمَّل متغيرات البيئة الأعلى إلى الأسفل بالترتيب التالي المذكور وانتبه إلى عملية تحميل المتغير تتوقف متى ما عثر على قيمته أولًا وتهمل الملفات الأخرى اللاحقة.

1. process.env
2. env.$(NODE_ENV).local.
3. env.local.
4. env.$(NODE_ENV).
5. env.

أي إن ضُبطت NODE_ENV إلى development وعرفت متغير بيئة في الملف env.development.local. والملف env. فالقيمة التي ستستعمل هي المعرفة في الملف الأول وتهمل تلك المعرفة في الملف env..

ملاحظة: القيم المسموحة من أجل NODE_ENV هي: production أو development أو test.

أمثلة

• Environment Variables

المصادر

• الصفحة Environment Variables من توثيق Next.js الرسمي.