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

تنبيه: هذا التوثيق خاص بالنسخة 9.4 وما بعدها من Next.js، فإن كنت تستخدم نسخة أدنى حدّث نسختك أو راجع توثيق الواجهة البرمجية- فقرة متغيرات البيئة.

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

• استخدام env.local. لتحميل متغيرات البيئة.
• كشف متغيرات البيئة للمتصفح بإضافة البادئة _NEXT_PUBLIC.

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

تدعم 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 بالقيمة الصحيحة أثناء بناء التطبيق. يعني ذلك أن الكائن process.env ليس كائنًا معياريًا في JavaScript، ولن تكون قادرًا على تفكيك الكائن. لا بد من الإشارة إلى متغيرات البيئة كالتالي:

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

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

# .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/.

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

لا تُعد متغيرات البيئة متغيرات في 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

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

لا نحتاج عادة إلى أكثر من الملف 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

يمكن تهيئة متغيرات البيئة من خلال إعدادات المشروع عند نشر تطبيق Next.js على Vercel. تُهيا جميع متغيرات البيئة في هذا المكان حتى تلك المستخدمة في مرحلة التطوير والتي يمكن تنزيلها على حاسوبك بعد ذلك.

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

vercel env pull .env.local

عندما تستخدم واجهة سطر الأوامر الخاصة بمنصة Vercel عليك التأكد من إضافة الملف vercelignore. الذي يشير إلى الملفات التي لا يجب رفعها، وهي عمومًا نفس الملفات التي يتضمنها الملف gitignore. (إن نشرت التطبيق على git).

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

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

يُستخدم الملف الأخير عندما تُجري الاختبارات بأدوات مثل "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)، تُحمَّل متغيرات البيئة من المصادر التالية من الأعلى إلى الأسفل. وانتبه إلى أن بقية الملفات غير قادرة على إلغاء قيم الملف env إن وجد في أية مرحلة (أو بيئة).

• بيئة الإنتاج NODE_ENV=production:
  1. env.production.local.
  2. env.local.
  3. env.production.
  4. env.
• بيئة التطوير NODE_ENV=development:
  1. env.development.local.
  2. env.local.
  3. env.development.
  4. env.
• بيئة الاختبار NODE_ENV=test:
  1. env.test.local.
  2. env.test.
  3. env.

ملاحظة: لا يُحمّل الملف env.local. في مرحلة الاختبار NODE_ENV=test.

المصادر

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