فهم ملف .env في Node.js

ما هو ملف .env؟

يُستخدم ملف .env لتخزين قيم الإعدادات لتطبيقك.

مثال:

PORT=5000
DB_URL=mongodb://localhost:27017/myapp
JWT_SECRET=mySecretKey

بدلاً من تثبيت هذه القيم داخل الكود، نبقيها منفصلة.

وهذا يجعل التطبيق:

• أنظف

• أسهل في الإدارة

• أكثر أماناً

• مختلفاً بين التطوير والإنتاج

لماذا لا نخزّن كل شيء مباشرة في الكود؟

مثال سيئ:

const password = "mypassword123";

تخيّل رفع هذا إلى GitHub بالخطأ.

باستخدام .env يكون الأمر أكثر أماناً:

DB_PASSWORD=mypassword123

ثم داخل Node.js:

process.env.DB_PASSWORD

كيف يقرأ Node.js ملف .env

Node.js لا يقرأ ملفات .env تلقائياً.

عادة نستخدم حزمة اسمها dotenv.

ثبّتها:

npm install dotenv

ثم حمّلها:

require("dotenv").config();

الآن يمكنك الوصول للقيم هكذا:

const port = process.env.PORT;

مهم: لا ترفع ملف .env أبداً إلى GitHub

أضف هذا إلى .gitignore:

.env

قد يحتوي .env على مفاتيح خاصة، وإبقاؤها خاصة أمر مهم جداً.

أولوية متغيرات البيئة في Node.js

هنا يختلط الأمر على كثير من المبتدئين. يمكن أن تأتي متغيرات البيئة من أماكن متعددة.

مثلاً:

• متغيرات بيئة النظام

• ملف .env

• إعدادات PM2

• Docker

• إعدادات مزوّد الاستضافة

يتبع Node.js ترتيب أولوية.

ترتيب الأولوية الأساسي

عادة يكون الترتيب كالتالي:

1. متغيرات بيئة النظام

2. متغيرات بيئة PM2

3. ملف .env

4. القيم الافتراضية في الكود

مثال:

افترض أن .env يحتوي:

PORT=3000

لكنك تشغّل التطبيق هكذا:

PORT=8000 node server.js

حينها سيستخدم التطبيق 8000

لأن متغيرات النظام تتجاوز .env.

استخدام .env مع PM2

إذا استخدمت PM2، تصبح إدارة البيئة أهم.

يسمح PM2 بتعريف متغيرات البيئة مباشرة داخل إعدادات ecosystem.

module.exports = {
  apps: [
    {
      name: "my-app",
      script: "./server.js",

      env: {
        NODE_ENV: "development",
        PORT: 3000
      },

      env_production: {
        NODE_ENV: "production",
        PORT: 8000
      }
    }
  ]
};

تشغيل PM2 في الإنتاج

pm2 start ecosystem.config.js --env production

سيستخدم PM2 قيم env_production.

PM2 مقابل .env — أيهما له الأولوية؟

إذا احتوى كلاهما على نفس المتغير:

.env

PORT=3000

PM2:

env: {
  PORT: 8000
}

فالقيمة النهائية عادة تكون:

8000

لأن متغيرات PM2 تتجاوز .env.

أفضل ممارسة

إعداد جيد:

.env

خزّن القيم المحلية/الخاصة.

PM2

خزّن إعدادات بيئة النشر/التشغيل.

مثال

# ملف .env
DB_URL=mongodb://localhost/test
JWT_SECRET=abc123

PM2:

env_production: {
  NODE_ENV: "production",
  PORT: 8000
}

هذا يبقي الأمور منظمة.

أخطاء شائعة

1. نسيان تحميل dotenv

require("dotenv").config();

بدون هذا، لن تُحمَّل قيم .env.

2. إضافة مسافات

❌ خطأ:

PORT = 3000

✅ صحيح:

PORT=3000

3. رفع .env إلى GitHub

استخدم دائماً:

.env

4. استخدام أسماء متغيرات مختلفة

❌ خطأ:

DATABASE_URL=abc

✅ الكود:

process.env.DB_URL

سيُرجع هذا undefined.

نصيحة للإنتاج

في خوادم الإنتاج الحقيقية، كثير من المطورين لا يستخدمون ملفات .env أصلاً.

بدلاً من ذلك يستخدمون:

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

• أسرار Docker

• إعدادات منصات السحابة

• إعدادات PM2

وهذا عادة أكثر أماناً.

أفكار ختامية

تجعل ملفات .env تطبيقات Node.js أنظف وأكثر أماناً وأسهل في الإدارة.

بمجرد فهم نظام الأولوية بين:

• .env

• متغيرات النظام

• PM2

• القيم الافتراضية

ستتجنب كثيراً من مشاكل النشر.

ابدأ ببساطة، أبقِ الأسرار خارج الكود، ونظّم متغيرات البيئة من البداية.

هذه العادة الصغيرة توفّر كثيراً من المتاعب لاحقاً.