Orbit
متغيرات البيئة
Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…
متغيرات البيئة
متغيرات البيئة تحمل الإعدادات والأسرار التي يحتاجها تطبيقك أثناء وقت البناء والتشغيل، مثل مفاتيح API وعناوين URL لقواعد البيانات وأعلام الميزات، وكل هذا بدون أن يكون موجوداً في المستودع الخاص بك. يغطي هذا الدليل موقع وجودها في Orbit وكيفية عمل النطاق والأولوية وتحديد القيمة كسرية والاستيراد والتصدير بالجملة والأخطاء التي تنتج متغيراً يبدو أنه غير محدد دائماً.
موقع وجودها
افتح مشروعك في Orbit وانقر على علامة التبويب Env vars عند /orbit/<project-id>/env-vars.
تنظم الصفحة القسم إلى أقسام:
- All environments في الأعلى: متغيرات على مستوى المشروع متاحة في كل بناء.
- قسم قابل للطي لكل بيئة (Production و Staging وأي معاينات) يحتوي على تجاوزات تلك البيئة.
فوق القائمة توجد مربع بحث وعامل تصفية Secrets only وهما الطريقة السريعة عبر قائمة طويلة.
كيفية عمل النطاق
| النطاق | ما يؤثر عليه |
|---|---|
| جميع البيئات (على مستوى المشروع) | يتم حقنه في كل بناء لهذا المشروع |
| تجاوز على مستوى البيئة | ينطبق فقط على تلك البيئة الواحدة، ويتفوق على القيمة على مستوى المشروع بنفس المفتاح |
الترجمة على الصفحة توضح القاعدة بوضوح: متغيرات على مستوى المشروع متاحة في كل بناء، والتجاوزات على مستوى البيئة لها الأولوية.
الإعداد النموذجي هو متغير على مستوى المشروع DATABASE_URL يشير إلى قاعدة بيانات اختبار، مع تجاوز على مستوى الإنتاج يشير إلى قاعدة البيانات الحقيقية. عمليات البناء في الإنتاج تحصل على قاعدة البيانات الحقيقية وكل شيء آخر يحصل على قاعدة الاختبار، وأي شيء تضيفه لاحقاً لن يسرب بطريق الخطأ بيانات اعتماد الإنتاج إلى معاينة.
توجد أيضاً عنصر تحكم Available in على متغيرات على مستوى المشروع، مما يتيح لك استبعاد أنواع بيئة معينة (production، staging، preview) من متغير هو بخلاف ذلك على مستوى المشروع.
التفاصيل الكاملة عن نطاق كل بيئة بما في ذلك الأسباب الأمنية موجودة في تعيين متغيرات البيئة لكل بيئة.
يتم حقن متغير على مستوى المشروع في عمليات بناء معاينة الفرع وعناوين URL للمعاينة قابلة للوصول بشكل علني من قبل أي شخص لديه الرابط. بيانات اعتماد قاعدة بيانات الإنتاج ومفاتيح الدفع المباشرة والرموز الإدارية يجب أن تقتصر على الإنتاج فقط. هذا هو أهم شيء يجب القيام به بشكل صحيح على هذه الصفحة.
إضافة متغير
- مرر لأسفل إلى نموذج Add variable في أسفل علامة التبويب Env vars.
- أدخل KEY على سبيل المثال
NEXT_PUBLIC_API_URL. - أدخل value.
- اختر Scope: All environments (project-wide) أو تجاوز بيئة محددة.
- إذا اخترت مستوى المشروع استخدم أزرار Available in لإلغاء تحديد أي أنواع بيئة لا يجب أن يصل إليها هذا المتغير.
- حدد Mark as secret لأي شيء حساس.
- انقر فوق Add.
يخبرك النموذج بما يقصد فعله قبل أن تلتزم به: يظهر تجاوز بيئة تنبيهاً يقول أنه سينطبق فقط على عمليات بناء تلك البيئة وتظهر متغيرات محدودة على مستوى المشروع أي أنواع بيئة سيتم حقنها فيها.
متى تدخل التغييرات حيز التنفيذ
إضافة أو تحرير أو حذف متغير لا يغير النشر المباشر حالياً. يتم حقن المتغيرات عند تشغيل البناء لذا يسري التغيير من النشر التالي فصاعداً. أعد نشر بعد تغيير أي شيء يعتمد عليه تطبيقك.
Orbit صريح بشأن هذا. افتح صفحة تفاصيل النشر وإذا تغيرت الإعدادات منذ بنائها ستحصل على تنبيه Environment variables updated since this deployment يخبرك أن التغيير لن يدخل حيز التنفيذ حتى تعيد النشر.
أسرار
حدد Mark as secret لأي شيء لن تلصقه في محادثة: مفاتيح API وكلمات مرور قاعدة البيانات والرموز ومفاتيح التوقيع.
قيم السرية مخفية في اللوحة وتحمل شارة secret. تظهر القيم غير السرية علامة (plain).
لا يمكن قراءة قيمة السرية مرة أخرى بعد حفظها وليس بواسطتك وليس من قبل أي شخص آخر في اللوحة. يمكنك استبدالها (انقر فوق رمز التحرير واكتب قيمة جديدة وحفظ) لكن لا يمكنك الكشف عنها. احتفظ بنسختك الخاصة في مدير كلمات المرور قبل أن تحفظها هنا.
Orbit يتتبع أيضاً المدة التي كانت القيمة موجودة فيها ويظهر شارة عمر على المتغيرات الأقدم مع تلميح يقترح الدوران. هذا دفعة وليس فرضاً.
التحرير والحذف
انقر فوق رمز التحرير بجانب متغير لتغيير قيمته. انقر فوق Delete لإزالته وتأكيد: يحذر الحوار من أن عمليات البناء التي تعتمد عليها ستنقطع وهذا هو الوصف الدقيق لما يحدث عند النشر التالي.
الاستيراد والتصدير بالجملة
يتعامل زران في أعلى علامة التبويب مع العمل بالجملة.
Import .env يفتح مربع لصق. الصق محتويات ملف .env واختر نطاقاً و Orbit يخبرك بعدد المتغيرات التي اكتشفتها وعددها الذي ستحدده كسرية. يوضح المفاتيح تلقائياً بناءً على أسمائها لذا أي شيء يحتوي على SECRET و TOKEN و KEY و PASSWORD وما شابه يتم تحديده كسري قبل الاستيراد. هناك خيار Overwrite existing variables with the same key مطفأ بشكل افتراضي.
Download .env ينتج قالباً يحتوي على أسماء المتغيرات فقط بدون قيم. يُقصد به أن يتشارك مع زميل يملأ بعد ذلك قيمه الخاصة وليس استخدامه كنسخة احتياطية.
تنزيل قالب .env لا يتضمن أبداً قيماً بما في ذلك المتغيرات غير السرية. لا توجد طريقة لتصدير القيم من Orbit. إذا كنت بحاجة إلى نسخة من القيمة خذها من حيث أنشأتها في الأصل.
نسخ المتغيرات بين البيئات
لوحة Copy variables between environments تنسخ مجموعة كاملة من نطاق إلى آخر. اختر From (على مستوى المشروع أو بيئة محددة) و To حدد اختياراً Overwrite variables that already exist in the target وانقر فوق Preview لترى بالضبط كم ستضاف وتحدث وتخطى قبل أن تلتزم.
توجد أيضاً صفحة Env sync check التي تقارن الإنتاج والإرسال المرحلي مفتاحاً تلو مفتاح وتقرر ما هو في واحد فقط وما يختلف وما يطابق. إنها الأداة المناسبة لـ "لماذا تعمل المرحلة المؤقتة والإنتاج لا يعمل".
مشاركة المتغيرات عبر المشاريع
إذا كانت عدة مشاريع تحتاج إلى نفس بيانات الاعتماد استخدم env group بدلاً من نسخها إلى كل مشروع. اذهب إلى Orbit ثم Env groups أنشئ مجموعة أضف متغيرات إليها وربط المشاريع التي تحتاجها.
يتم حقن متغيرات المجموعة في وقت البناء وتتفوق متغيرات على مستوى المشروع والبيئة على متغيرات المجموعة. يمكن أن يكون لديك ما يصل إلى 20 مجموعة على حساب.
ملاحظات الإطار
أي متغيرات تصل إلى المتصفح يتم تحديدها بواسطة الإطار الخاص بك وليس بواسطة Orbit. يحقن Orbit كل شيء في النطاق ويقرر الإطار ما يجب فضحه.
- Next.js: المفاتيح بادئة
NEXT_PUBLIC_يتم حقنها في حزمة المتصفح في وقت البناء. كل شيء آخر يبقى على جانب الخادم. - Vite: المفاتيح بادئة
VITE_يتم فضحها للمتصفح. كل شيء آخر فقط في وقت البناء. - Node.js apps: كل شيء في النطاق على
process.envأثناء البناء وفي وقت التشغيل عندما يكون Server mode مفعلاً.
أبداً لا تحدد قيمة كسرية وبعد ذلك بادئة أيضاً NEXT_PUBLIC_ أو VITE_. العلم السري يتحكم فقط في ما إذا كانت اللوحة تظهر لك القيمة، تتحكم البادئة في ما إذا كان الإطار الخاص بك يشحنها لكل زائر متصفح. البادئة تفوز.
التحقق مما يتلقاه البناء فعلاً
تسرد كل صفحة تفاصيل النشر keys متغيرات البيئة التي تم حقنها في وقت البناء وتميزها مقابل الإعدادات الحالية الخاصة بك: مضافة ومتغيرة وتمت إزالتها وبدون تغيير. مفاتيح اللون الأزرق جاءت من تجاوز خاص بالبيئة والمفاتيح الرمادية من مستوى المشروع. لم يتم تخزين القيم أو عرضها أبداً لكن تمرير مؤشر فوق مفتاح يعطي بصمة SHA-256 وهذا يكفي لتأكيد أن بيئتين تحتويان على نفس القيمة دون الكشف عنها.
هذا هو الجواب النهائي على "هل وصل متغيري فعلاً إلى البناء". تحقق منه قبل أن تغير أي شيء آخر.
استكشاف الأخطاء
المتغير غير محدد في وقت التشغيل. تحقق من أن النشر لاحق للتغيير ثم تحقق من أن النطاق يغطي هذه البيئة ثم تحقق من قواعد بادئة الإطار أعلاه. بهذا الترتيب.
يعمل في الإنتاج لكن ليس في معاينة. المتغير مقتصر على الإنتاج فقط أو متغير على مستوى المشروع لديه preview غير محدد تحت Available in. هذا عادة مقصود.
يعمل محلياً لكن ليس في البناء. ملف .env المحلي الخاص بك ليس في المستودع وليس يجب أن يكون. استورده باستخدام Import .env واختر النطاق الصحيح.
المرحلة المؤقتة تفتقد كل شيء الإنتاج لديه. قم بتشغيل Inherit production env vars في Settings تحت Staging: environment variables أو استخدم Copy variables between environments.