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

Question

Accepted Answer

يقوم Next.js بتحميل متغيرات البيئة من ملفات `.env`، مع قاعدة أمان مهمة: المتغيرات تكون **قاصرة على الخادم فقط بشكل افتراضي**، والمتغيرات التي تحمل البادئة `NEXT_PUBLIC_` فقط هي التي يتم عرضها للمتصفح.

## الملفات

```text
.env                # loaded in all environments
.env.local          # local overrides — GITIGNORED (put secrets here)
.env.development    # only in `next dev`
.env.production     # only in production builds
```

## قاعدة البادئة الحاسمة

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com  # exposed to the browser
```

```tsx
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL;          // ✅ works on the server

// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ works
const secret = process.env.DATABASE_URL;      // ❌ undefined in the browser
```

قاعدة البادئة هذه هي **ميزة أمان**: فهي تمنعك من شحن كلمات مرور قاعدة البيانات أو أسرار API إلى العميل عن طريق الخطأ. المتغير غير المعني بالبادئة ببساطة لا يوجد في حزم المتصفح.

## كيفية دمج قيم NEXT_PUBLIC

```text
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
```

نظراً لأنها مدمجة في وقت البناء، فإن تغيير قيمة `NEXT_PUBLIC_` يتطلب **إعادة بناء** — ولا يجب أبداً وضع الأسرار الحقيقية خلف البادئة (ستكون مرئية في الحزمة لأي شخص).

## أفضل الممارسات

```text
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
```

## لماذا هذا مهم

نموذج "قاصر على الخادم فقط" مع خيار الاشتراك `NEXT_PUBLIC_` هو حاجز Next.js ضد تسرب الأسرار إلى العميل — خطأ شائع وخطير.

فهم متغيرات الوصول إلى المتصفح، وأن الأوقات العامة مدمجة في وقت البناء، ومكان تخزين الأسرار (ملف `.env.local` المتجاهل) أمر ضروري للوظيفة والأمان معاً.