تعيين متغيرات البيئة لكل بيئة

Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence…

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

لماذا هذا مهم

معاينة الفرع تحصل على عنوان URL عام. يمكن لأي شخص لديه الرابط تحميله. إذا كان المتغير نطاقه لكل بيئة، يتم حقنه في بناء المعاينة، وأيًا كان ما تفعله المعاينة به، فإنها تفعله ببيانات اعتماد الإنتاج الخاصة بك.

هذا هو السبب كله لوجود هذه الصفحة. كل شيء أدناه يخدم قاعدة واحدة: أسرار الإنتاج تنتمي إلى نطاق الإنتاج، وليس في أي مكان آخر.

كيفية عمل النطاق

كل متغير له نطاق يقرر متى يتم حقنه في وقت البناء.

النطاق	يتم الحقن إلى
جميع البيئات (على مستوى المشروع)	كل بناء لهذا المشروع، إلا إذا قيدته
تجاوز بيئة محددة	بناء تلك البيئة الواحدة فقط

عندما يكون المفتاح نفسه موجودًا على كلا المستويين، يفوز المستوى الأكثر تحديدًا. تجاوز على مستوى البيئة يتفوق على متغير على مستوى المشروع بنفس المفتاح. تذكر صفحة متغيرات البيئة هذا في العنوان الفرعي لقسم جميع البيئات: متغيرات على مستوى المشروع متاحة في كل بناء، وتجاوزات على مستوى البيئة لها الأسبقية.

يمكن أيضًا تضييق متغيرات على مستوى المشروع دون أن تصبح تجاوزًا. يوفر عنصر تحكم متاح في ثلاثة أنواع بيئات (production, staging, preview) ويمكنك إلغاء تحديد أي منها.

إضافة متغير مع نطاق

افتح مشروعك في Orbit وانقر على علامة التبويب Env vars.
مرر لأسفل إلى نموذج Add variable في الأسفل.
ملء KEY والقيمة.
استخدم القائمة المنسدلة Scope:
- All environments (project-wide) يحقنه في كل بناء.
- [Environment name] only ([type] override) ينطقه على تلك البيئة الواحدة فقط.
إذا اخترت project-wide، استخدم أزرار Available in لإلغاء تحديد أنواع البيئات التي لا يجب أن يصل إليها هذا المتغير.
حدد Mark as secret لأي شيء حساس.
انقر فوق Add.

قبل الالتزام، يخبرك النموذج بما سيفعله. يظهر التجاوز إشعارًا يقول أنه سيتم تطبيقه فقط على بناءات تلك البيئة وأن متغيرات على مستوى المشروع لا تزال تنطبق في مكان آخر. يظهر متغير project-wide مقيد بالضبط أنواع البيئات التي سيتم حقنه فيها.

إضافة متغير خاص بالإنتاج فقط

طريقتان متكافئتان:

في القائمة المنسدلة Scope، اختر بيئة الإنتاج الخاصة بك (تحمل شارة خضراء production)، أو
اترك النطاق كـ All environments وألغِ تحديد staging و preview تحت Available in.

بأي طريقة، المتغير غائب عندما تعمل معاينة أو بناء تدريج.

"غائب" يعني غائب، وليس فارغًا. الكود الذي يقرأ process.env.STRIPE_SECRET_KEY في بناء معاينة يحصل على undefined، وحسب طريقة كتابته قد يرمي في وقت البناء أو، ما هو أسوأ، يأخذ فرعًا خاطئًا بصمت. أعط المعاينات قيمة وضع اختبار بدلاً من عدم وجود قيمة على الإطلاق.

النمط الآمن

النمط الذي يحل هذه المشكلة بنظافة لمعظم المشاريع:

أضف بيانات اعتماد الإنتاج المحددة النطاق لبيئة الإنتاج فقط.
أضف متغيرًا بنفس المفتاح، يحمل قيمة اختبار أو وضع رملي، في نطاق على مستوى المشروع.

عمليات بناء الإنتاج تحصل على القيمة ذات النطاق الإنتاجي لأن النطاق الأكثر تحديدًا يفوز. المعاينات والتدريج تحصل على قيمة الاختبار. لا شيء غير محدد في أي مكان، وبيانات اعتماد الإنتاج لا تصل أبدًا إلى معاينة.

طبقه على:

عناوين URL قاعدة بيانات الإنتاج
مفاتيح سر مزود الدفع، باستخدام مفاتيح الاختبار للمزود للمعاينات
مفاتيح إرسال البريد الإلكتروني، حتى لا تتمكن معاينة من إرسال بريد للعملاء الحقيقيين
رموز الإدارة والأسرار الموقعة
أي شيء بتكلفة لكل استدعاء

وراثة متغيرات الإنتاج في التدريج

إذا كانت بيئة التدريج الخاصة بك قريبة من الإنتاج وتريد فقط تجاوز بعض القيم، فلا يجب عليك تكرار كل شيء.

في Settings، ابحث عن Staging: environment variables وشغّل Inherit production env vars. يتم دمج متغيرات الإنتاج بعد ذلك في بناءات التدريج بـ أولوية أقل من تجاوزات خاصة بالتدريج، لذا يفوز أي شيء تعيينه بشكل صريح على التدريج.

الوراثة تنسخ قيم الإنتاج إلى بناءات التدريج، بما في ذلك بيانات اعتماد الإنتاج. قم بتشغيله فقط إذا كانت بيئة التدريج الخاصة بك محمية. يدعم التدريج كلا من كلمة مرور وقائمة IP allowlist، في أقسام Staging: access protection و Staging: IP allowlist في Settings. تشغيل الوراثة لبيئة تدريج غير محمية يعيد بالضبط التعريض الذي تتعلق به هذه الصفحة.

عرض وتحرير المتغيرات الموجودة

يجمع علامة التبويب Env vars المتغيرات إلى:

All environments في الأعلى، يحتوي على متغيرات على مستوى المشروع
قسم قابل للطي لكل بيئة، يحتوي على تجاوزات تلك البيئة، مع عدد كم عددها

فوقها يوجد صندوق بحث وفلتر Secrets only.

تظهر الشارات بجانب اسم كل متغير أنواع البيئات التي يصل إليها. متغير يظهر production و preview لكن ليس staging سيكون غائبًا من بناءات التدريج، وصف الشارة هذا هو أسرع طريقة لتدقيق قائمة طويلة.

انقر فوق رمز التحرير لتغيير قيمة. لا يمكن الكشف عن القيمة الحالية لمتغير سري، يمكن فقط استبدالها.

النسخ والمقارنة بين البيئات

Copy variables between environments ينسخ مجموعة كاملة من نطاق إلى آخر. اختر From و To، حدد بشكل اختياري Overwrite variables that already exist in the target، وانقر فوق Preview لمعرفة عدد الذي سيتم إضافته وتحديثه وتخطيه قبل الالتزام.

تقارن صفحة Env sync check الإنتاج والتدريج مفتاحًا تلو الآخر وتقرير ما يوجد في واحد فقط، ما له قيم مختلفة، وما يطابق. إنه أول محطة صحيحة لـ "التدريج يعمل والإنتاج لا"، أو العكس.

القيم المختلفة بين الإنتاج والتدريج طبيعي ومتوقع لمعظم الأسرار. تقول صفحة المزامنة ذلك. ما تبحث عنه هو مفتاح موجود في بيئة واحدة وغائب عن الآخر.

مشاركة المتغيرات عبر المشاريع

إذا احتاج عدة مشاريع إلى نفس بيانات الاعتماد، استخدم مجموعة env بدلاً من لصقها في كل مشروع. انتقل إلى Orbit، ثم Env groups، أنشئ مجموعة، أضف المتغيرات، وربط المشاريع التي تحتاجها.

يتم حقن متغيرات المجموعة في وقت البناء وتجلس في الأسفل من ترتيب الأسبقية: متغيرات على مستوى المشروع وعلى مستوى البيئة كلاهما يسبق متغيرات المجموعة. يمكن أن تحتوي على حتى 20 مجموعة على حساب.

حذف مجموعة يزيل تلك المتغيرات من عمليات البناء المستقبلية لكل مشروع مرتبط. عمليات البناء المكتملة بالفعل لا تتأثر.

الاستيراد بالجملة

يفتح زر Import .env صندوق لصق. ألصق ملف .env، اختر نطاقًا، وتقرير Orbit كم عدد المتغيرات التي وجدتها وكم عددها ستضع علامة كسري. المفاتيح التي تحتوي على SECRET, TOKEN, KEY, PASSWORD والشروط المماثلة يتم وضع علامة عليها تلقائيًا. هناك خيار Overwrite existing variables with the same key، معطل بشكل افتراضي.

Download .env ينتج قالبًا من أسماء المتغيرات فقط، بدون قيم، لمشاركة مع زميل سيوفر الخاص به.

اختر النطاق في حوار الاستيراد قبل أن تنقر فوق Import، وليس بعده. استيراد ملف إنتاج .env كامل في نطاق على مستوى المشروع يدفع كل بيانات اعتماد الإنتاج إلى عمليات البناء للمعاينة في إجراء واحد، والإصلاح هو حذف وإعادة إضافتها، وليس تغيير إعدادات.

التحقق مما استقبله البناء فعليًا

تسرد صفحة تفاصيل كل نشر مفاتيح متغير البيئة المحقونة في وقت البناء وتقارنها مع التكوين الحالي الخاص بك: مضافة ومتغيرة وأزيلت وبدون تغيير. جاءت مفاتيح Teal من تجاوز خاص ببيئة محددة، والرمادية من مستوى المشروع.

لا يتم تخزين أو عرض القيم أبدًا. عند تحريك مفتاح يعطيك بصمة SHA-256، وهو ما يكفي للتأكد من أن بيئتين تحتفظان بنفس القيمة دون الكشف عنها.

إذا تغير التكوين بعد بناء النشر هذا، تقول الصفحة ذلك مع إشعار Environment variables updated since this deployment وتذكرك أن التغيير لن يسري إلا عند إعادة النشر.

تغييرات المتغيرات لا تنطبق أبدًا على النشر الذي يعمل بالفعل. يتم حقنها عند تشغيل البناء. بعد تغيير أي شيء يعتمد عليه تطبيقك، أعد النشر.

قراءة ذات صلة

Environment Variables للأساسيات والأسرار وقواعد بادئة الإطار
Branch Preview Deployments in Orbit لكيفية عمل المعاينات العامة
Viewing Build Logs لاختلاف متغير وقت البناء