0Pricing
Frontend Academy · درس

متغيرات البيئة في CI

خزّن الأسرار في GitHub Secrets، وحقنها في عملية البناء باعتبارها متغيرات بيئة، والوصول إليها في Vite باستخدام import.meta.env أو في Next.js باستخدام process.env

متغيرات البيئة في CI درس مجاني في Frontend Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Frontend Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Frontend Academy 4 دروس في المجموع.

لماذا نستخدم بيئات مختلفة؟

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

عام أم خاص بالخادم؟

متغيرات الواجهة الأمامية المضمّنة في الحزمة عامة، ويمكن لأي شخص رؤيتها باستخدام أدوات المطوّر. لا تضع الأسرار فيها مطلقًا. أما متغيرات جانب الخادم (المستخدمة في الدوال serverless أو SSR أو مسارات API) فيمكن أن تكون أسرارًا حقيقية.

متغيرات بيئة Vite

يعرِض Vite المتغيرات التي تحمل البادئة VITE_ لشفرة العميل عبر import.meta.env.

# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS={"newOnboarding":true}

# In code:
const apiUrl = import.meta.env.VITE_API_URL;

# DEV_ONLY or NEVER PREFIXED vars are NOT exposed:
SECRET_KEY=xxx  # not accessible to client code

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

يضع Next البادئة NEXT_PUBLIC_ للمتغيرات العامة. أما المتغيرات الخاصة بالخادم فلا تحمل بادئة (وتُستخدم في Route Handlers وgetServerSideProps).

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com  # client-accessible
DATABASE_URL=postgres://...                  # server-only

# Client:
const url = process.env.NEXT_PUBLIC_API_URL;

# Server (API route):
const db = process.env.DATABASE_URL;

ملفات .env المحلية

استخدم .env.local للتجاوزات الشخصية، و.env.development و.env.production للإعدادات الافتراضية الخاصة بكل بيئة. أضف .env.local إلى .gitignore، ولا ترفع الأسرار إلى المستودع مطلقًا.

# .gitignore
.env.local
.env.*.local

# Commit only .env.example with placeholder values:
VITE_API_URL=https://api.example.com
DATABASE_URL=

تخزين الأسرار في GitHub Actions

أضف الأسرار في إعدادات المستودع → Secrets and variables → Actions. يمكنك الوصول إليها عبر secrets.NAME.

# .github/workflows/deploy.yml
- name: Deploy
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx vercel --token $VERCEL_TOKEN --prod
    npx sentry-cli releases new $RELEASE

أسرار خاصة بكل بيئة

تتيح GitHub Environments تحديد نطاق الأسرار لبيئة معينة (مثل staging أو production) مع بوابات موافقة اختيارية، وذلك من خلال الإعدادات → Environments.

# Job that requires environment:
deploy-prod:
  environment: production   # requires reviewer approval if configured
  steps:
    - run: deploy
      env:
        DB_URL: ${{ secrets.DB_URL }}  # only prod's DB_URL is exposed

متغيرات البيئة لدى مزوّد الاستضافة

تتيح Vercel وNetlify وCloudflare جميعها متغيرات البيئة لعملية البناء وبيئة التشغيل. اضبطها من لوحة التحكم أو عبر CLI.

# Vercel:
vercel env add VITE_API_URL production
vercel env add VITE_API_URL preview

# Netlify:
netlify env:set VITE_API_URL https://api.example.com

# Cloudflare Pages:
wrangler pages secret put API_URL

لا تضع الأسرار مباشرةً في حزم الواجهة الأمامية

إذا كانت قيمة ما موجودة في JavaScript الخاص بالعميل، فهي عامة. صُمّمت مفاتيح API الخاصة بحزم SDK التابعة لجهات خارجية (مثل مفتاح Stripe القابل للنشر ومفتاح بحث Algolia) لتكون عامة. أما أي شيء آخر، مثل مفاتيح API الخاصة بالخادم، فيجب أن يبقى في الواجهة الخلفية.

التحقق من متغيرات البيئة وقت البناء

استخدم zod أو envalid لإفشال عمليات البناء إذا كانت متغيرات البيئة المطلوبة مفقودة.

// env.ts
import { z } from 'zod';

const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_SENTRY_DSN: z.string().url().optional()
});

export const env = envSchema.parse(import.meta.env);
// Throws helpful error if VITE_API_URL is missing

وقت البناء مقابل وقت التشغيل

تُضمَّن متغيرات البيئة وقت البناء في الحزمة، لذا يتطلب تغييرها إعادة البناء. أما متغيرات البيئة وقت التشغيل (في مسارات Next API وNetlify Functions وCloudflare Workers) فتُقيَّم مع كل طلب. اختر النوع المناسب بناءً على ما إذا كانت القيمة يجب أن تتغير دون إعادة النشر.

تدوير الأسرار

دوّر الأسرار بانتظام (كل 90 يومًا) وبعد أي تغيير في الفريق. استخدم 1Password Secrets Automation أو AWS Secrets Manager أو خدمة مشابهة للحفاظ على حداثة الأسرار في CI دون تحديثات يدوية.

الأخطاء الشائعة

1) رفع ملف .env الذي يحتوي على أسرار حقيقية — استخدم git-secrets لمنع ذلك. 2) كشف متغيرات الخادم للعميل (بسبب البادئة الخاطئة). 3) نسيان ضبط متغيرات البيئة في عمليات نشر المعاينة. 4) خلط مفاتيح الاختبار ومفاتيح الإنتاج في البيئة نفسها.

تحقّق سريعًا

لماذا يجب أن تحمل متغيرات بيئة Vite المكشوفة للعميل البادئة VITE_؟

مراجعة: متغيرات البيئة في CI

المتغيرات العامة: تحمل بادئة (VITE_ وNEXT_PUBLIC_)، وتُضمَّن في الحزمة، ويمكن للمستخدمين رؤيتها. المتغيرات الخاصة بالخادم: لا تحمل بادئة، وتُستخدم في مسارات API أو SSR. أضف .env.local إلى .gitignore، وارفع .env.example. استخدم GitHub Secrets في CI، وGitHub Environments لتحديد نطاق أسرار الإنتاج. يضبط مزوّدو الاستضافة (Vercel وNetlify وCloudflare) المتغيرات لكل بيئة. تحقّق منها باستخدام zod وقت البناء.

الأسئلة الشائعة

هل درس «متغيرات البيئة في CI» مجاني؟

نعم — نص درس «متغيرات البيئة في CI» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Frontend Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Frontend Academy 4 دروس في المجموع.

ماذا ستتعلم في «متغيرات البيئة في CI»؟

خزّن الأسرار في GitHub Secrets، وحقنها في عملية البناء باعتبارها متغيرات بيئة، والوصول إليها في Vite باستخدام import.meta.env أو في Next.js باستخدام process.env تتمرن على Frontend Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Frontend Academy؟

لا تُشترط خبرة سابقة. Frontend Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «متغيرات البيئة في CI»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Frontend Academy هذا؟

نعم. كل درس في Frontend Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. GitHub Actions للواجهة الأمامية: lint وtest وbuild
  2. النشر إلى Vercel وNetlify وCloudflare Pages
  3. متغيرات البيئة في CI
  4. فحوصات Lighthouse الآلية
← العودة إلى Frontend Academy