process.env في Node.js: قراءة متغيرات البيئة

process.env كائن فيه خاصية لكل متغير بيئة مرّرته الصدفة إلى برنامج Node.js: process.env.PORT وprocess.env.DATABASE_URL وهكذا. المتغير غير المضبوط يُقرأ على أنه undefined، والمتغير المضبوط هو نص دائمًا. اقرأه مرة واحدة عند بدء التشغيل، وأعطه قيمة افتراضية، وحوّله إلى النوع الذي تحتاجه.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

طبع shop on port 8080 in eu-west (لم يُضبط REGION أبدًا، فحلّت قيمته الافتراضية محله)، ثم string number: المتغير نص إلى أن يحوّله Number(). احذف الإسنادين الأولين وشغّل من جديد لترى كل القيم الافتراضية.

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

تأتي المتغيرات من المكان الذي يُشغَّل منه Node.js. في الطرفية:

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

لمنصات الاستضافة (Heroku وRender وVercel وDocker وKubernetes) صفحة إعدادات أو ملف للغرض نفسه؛ وتقرؤها شيفرتك بالطريقة ذاتها.

كل شيء نص

من هنا تأتي معظم أخطاء process.env. القيمتان 'false' و'0' نصان غير فارغين، لذلك تُعتبران صحيحتين (truthy):

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

طبع الفحص الساذج debug is ON لمتغير قيمته false، فقارن بالنص الدقيق الذي تتوقعه. أما الأرقام، فـ Number(process.env.X) يحوّل القيمة الغائبة إلى NaN، لذا طبّق القيمة الافتراضية قبل التحويل، كما فعل المثال الأول بـ ??.

NODE_ENV

NODE_ENV عُرف متّبع وليس ميزة في Node.js: لا يضبطه Node.js أبدًا. المكتبات هي التي تقرؤه. فمثلًا يخفي Express تتبّع المكدس (stack trace) من صفحات الأخطاء حين تكون قيمته production، وتتخطى أدوات كثيرة الفحوص الخاصة بالتطوير.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

طبع mode: production وverbose logs: false؛ غيّر 'production' إلى 'development' فينقلب السطر الثاني. التزم بالقيم production وdevelopment وtest، لأن المكتبات تبحث عن هذه الكلمات بالضبط.

ملفات .env: الخيار --env-file وdotenv

كتابة كل متغير قبل node تصبح مملة. يحفظها ملف .env في مجلد مشروعك، متغيرًا في كل سطر:

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

يقرؤه Node.js 20.6 وما بعده بخيار واحد، دون أي حزمة:

node --env-file=.env app.js

في النسخ الأقدم، أو إن كنت تفضّل ذلك، ثبّت الحزمة dotenv (npm install dotenv) وحمّلها في أعلى ملف الدخول تمامًا، قبل أن تقرأ أي شيفرة process.env:

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

لا يكتب أي منهما فوق متغير مضبوط مسبقًا في الصدفة، فتكون الأولوية لإعدادات الإنتاج على الملف.

توقّف مبكرًا عند غياب المتغيرات

غياب عنوان قاعدة البيانات يجب أن يوقف البرنامج عند بدء التشغيل برسالة واضحة، لا أن يتعطل عند أول طلب بعد ساعة:

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter((key) => !process.env[key]);

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

طبع Missing environment variables: API_KEY؛ أضف process.env.API_KEY = 'test'; في الأعلى فيطبع Config OK. في برنامج حقيقي، أتبِع الرسالة بـ process.exit(1)، لأن رمز الخروج غير الصفري هو الطريقة التي يعرف بها سكربت النشر أو منصة الحاويات أن بدء التشغيل فشل.

لا ترفع الأسرار إلى المستودع أبدًا

أضف .env إلى .gitignore في اليوم الذي تنشئه فيه. وارفع بدلًا منه .env.example فيه أسماء المتغيرات وقيم وهمية، ليعرف الآخرون ما يجب ضبطه. أي مفتاح دُفع إلى مستودع ولو مرة يجب اعتباره مسرّبًا واستبداله، حتى لو حذفت الـ commit لاحقًا.