متغيّرات البيئة

لماذا تهمّ متغيّرات البيئة

متغيّر البيئة هو قيمة مسمّاة توجد في بيئة تشغيل تطبيقك — منفصلةً عن شفرته المصدرية. فعندما يحتاج تطبيقك إلى مفتاح API، أو سلسلة اتصال بقاعدة بيانات، أو سرّ webhook لجهة خارجية، يقرأ تلك القيمة من البيئة عند بدء التشغيل بدلًا من إيجادها مكتوبة بشكل ثابت في ملف.

هذا الفصل يهمّ لسببين. الأول، أن الأسرار التي تعيش في الكود ينتهي بها المطاف في نظام التحكّم بالإصدارات. ودفعة واحدة عرضية إلى مستودع GitHub عام قد تكشف بيانات الاعتماد للإنترنت بأسره، والتدوير بعد التسرّب مؤلم. والثاني، أن البيئات المختلفة — التطوير على حاسوبك، والمرحلية لضمان الجودة، والإنتاج للمستخدمين الحقيقيين — تحتاج إلى قيم مختلفة لنفس المتغيّر. ومتغيّرات البيئة تجعل ذلك التبديل بسيطًا.

ضبط المتغيّرات في مايندلاب

لكل مشروع في مايندلاب لوحة بيئة تُعرّف فيها متغيّراتك. وللوصول إليها:

قيم التطوير مقابل الإنتاج

يحتفظ مايندلاب بمخازن متغيّرات منفصلة لبيئتي Development وProduction. وهذا يتيح لك استخدام مفتاح Stripe تجريبي وعنوان قاعدة بيانات محلي أثناء التطوير، بينما تستخدم بيئة الإنتاج بيانات اعتماد حيّة وقاعدة بياناتك السحابية — دون أي تغييرات في الكود.

عندما يدفع مايندلاب عملية نشر إلى Vercel أو Railway، يحقن متغيّرات الإنتاج مباشرةً في مخزن أسرار منصّة الاستضافة عبر واجهات API الخاصة بها. ولا تحتاج أبدًا إلى نسخ بيانات الاعتماد ولصقها في لوحة استضافة يدويًا.

الإشارة إلى المتغيّرات في الكود المولّد

يولّد مايندلاب كودًا يقرأ متغيّرات البيئة باستخدام النمط الاصطلاحي لكل لغة. وإليك الحالتين الأكثر شيوعًا:

في خادم FastAPI (Python)، تُحمَّل المتغيّرات باستخدام المكتبة القياسية:

import os
from fastapi import FastAPI

app = FastAPI()

# Loaded from the environment at startup — never hardcoded
DATABASE_URL = os.environ.get("DATABASE_URL")
STRIPE_SECRET_KEY = os.environ.get("STRIPE_SECRET_KEY")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")

if not DATABASE_URL:
    raise RuntimeError(
        "DATABASE_URL environment variable is not set. "
        "Add it in Project Settings > Environment."
    )

@app.get("/health")
def health():
    return {"status": "ok"}

في واجهة React الأمامية (Vite)، يجب أن تُسبَق المتغيّرات ببادئة VITE_ كي تُعرَض لحزمة المتصفّح. وهذه البادئة إجراء أمني — فالمتغيّرات التي تخلو منها لا تُضمَّن أبدًا في كود جانب العميل، حتى لو كانت موجودة في البيئة.

// Vite exposes only VITE_-prefixed variables to the browser
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
const stripePublicKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY;

// Never put secrets in VITE_ variables — they're visible in the browser
// Use VITE_ only for public, non-sensitive configuration

if (!apiBaseUrl) {
  console.error(
    "VITE_API_BASE_URL is not set. " +
    "Check Project Settings > Environment."
  );
}

في خادم Express (Node.js)، النمط مشابه لـ Python لكنه يستخدم process.env:

import express from "express";

const app = express();

const DATABASE_URL = process.env.DATABASE_URL;
const JWT_SECRET = process.env.JWT_SECRET;

if (!DATABASE_URL || !JWT_SECRET) {
  throw new Error(
    "Required environment variables are missing. " +
    "Check Project Settings > Environment."
  );
}

app.listen(process.env.PORT ?? 3001, () => {
  console.log("Server started");
});

المزامنة مع GitHub

عندما يزامن مايندلاب مشروعك مع GitHub، تُعالَج متغيّرات البيئة بعناية لمنع التسرّب العرضي:

# .env.example — committed to GitHub (no real values)
DATABASE_URL=
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
OPENAI_API_KEY=
JWT_SECRET=
APP_URL=http://localhost:3000

# .env — local only, never committed (in .gitignore)
DATABASE_URL=postgresql://postgres:password@localhost:5432/myapp_dev
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
OPENAI_API_KEY=sk-...
JWT_SECRET=a-long-random-string-here
APP_URL=http://localhost:3000

تدوير سرّ

تدوير السرّ — استبدال بيانات اعتماد مخترَقة أو منتهية الصلاحية بأخرى جديدة — ينبغي أن يتمّ بعناية لتجنّب التوقّف. وإليك التسلسل الآمن الذي تتبعه في مايندلاب: