Vercel: متغيرات البيئة دون .env في Git

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

تجد في الوثائق معلومات عملية حول استخدام Ailoot.

لماذا لا تحتاج إلى إضافة .env إلى Git#

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

يمكن لـ Next.js تحميل المتغيرات من ملفات .env* المحلية. لكن الملف المحلي وإعدادات المشروع على Vercel موقعان منفصلان. إذا لم يُرفع الملف إلى المستودع، فاضبط القيم بشكل منفصل على منصة الاستضافة. يضيف القالب القياسي create-next-app ملفات .env إلى .gitignore؛ وتحذّر وثائق Next.js من أنه ينبغي تقريبًا عدم رفعها إلى المستودع مطلقًا.

إذا كنت لا تزال غير متأكد مما يمكن تخزينه في ملفات المصدر، فابدأ بـفحص الأمان لمشروع أُنشئ باستخدام الذكاء الاصطناعي. أما هنا، فنتناول سؤالًا أضيق نطاقًا: أين تضبط إعدادات عملية نشر محددة على Vercel.

أولًا، حدّد أين يقرأ التطبيق المتغير#

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

بيئة Development مخصصة للتطوير المحلي. وPreview مخصصة لعمليات النشر للمعاينة، أما Production فهي للإصدار المنشور الرئيسي. قد تتضمن Preview إعدادات لفرع Git محدد؛ وهذه الإعدادات تتجاوز إعدادات Preview العامة التي تحمل الأسماء نفسها.

في مشروع Next.js، تكون المتغيرات التي لا تبدأ بـNEXT_PUBLIC_ متاحة على الخادم افتراضيًا. تتيح البادئة NEXT_PUBLIC_ تضمين القيمة في JavaScript المُرسل إلى المتصفح. وهذا مناسب لإعداد عام صريح، مثل تسمية إصدار غير سرية، لكنه غير مناسب لمفتاح API خاص. وحتى من دون هذه البادئة، يجب ألا تعيد شيفرة التطبيق سرًا إلى العميل يدويًا.

إذا لم تكن قد حددت إطار العمل بعد، فاطلب من الوكيل تحديده من ملفات المشروع. قد تساعدك مقارنة Astro وNext.js على فهم الفروق؛ ولا يمكنك تطبيق قاعدة NEXT_PUBLIC_ على كل تطبيقات React.

إعداد الاستضافة إحدى المهام المرتبطة بالعمل على تطبيق باستخدام وكيل ذكاء اصطناعي.

كيفية إضافة متغير إلى مشروع Vercel#

نفّذ الخطوات بنفسك في لوحة التحكم الرسمية. لا تعطِ الوكيل مفتاحًا حقيقيًا لإدخاله في النموذج، ولا تُرفق لقطة شاشة تظهر فيها قيمته.

1. افتح لوحة تحكم Vercel وحدد المشروع الصحيح. لا تعتمد فقط على تطابق اسم المستودع؛ تحقق من أنك تضبط التطبيق الذي تنوي فتحه.
2. انتقل إلى Environment Variables في الشريط الجانبي لإعدادات المشروع.
3. في Name، أدخل الاسم الذي يقرأه التطبيق، مثل SERVICE_API_KEY. هذا اسم توضيحي؛ إذا كانت الشيفرة تتوقع اسمًا آخر، فاستخدمه بالحروف نفسها تمامًا.
4. في Value، أدخل القيمة من مخزن بيانات الاعتماد لديك. لا تضعها في الشيفرة المصدرية أو في محادثة أو في سجل تحقق.
5. حدّد البيئة التي تحتاج إلى هذا الإعداد. استخدم Preview للتحقق من إصدار للمعاينة وProduction للإصدار الرئيسي. لا تُسنِد سرًا واحدًا تلقائيًا إلى جميع البيئات.
6. إذا كان إعداد Preview يخص فرعًا معينًا، فتحقق من الفرع المحدد ومن أي إعداد يتجاوزه ويحمل الاسم نفسه.
7. انقر Save.

تتيح Vercel متغيرات المشروع أثناء البناء وعند تشغيل Vercel Functions على جانب الخادم. لكن إتاحة قيمة داخل Vercel لا تعني أنه يمكن إرسالها إلى المتصفح؛ فهذا يعتمد على شيفرة التطبيق وقواعد إطار العمل.

لماذا تحتاج إلى عملية نشر جديدة بعد Save#

لا يؤدي حفظ متغير إلى تغيير عمليات النشر الحالية. تشترط وثائق Vercel إعادة نشر المشروع لكي يصل الإعداد الجديد إلى الإصدار الذي تستخدمه.

عند العمل عبر Git، يمكنك إنشاء عملية نشر Production جديدة بدفع commit إلى الفرع المحدد في Production Branch، وإنشاء عملية نشر Preview بدفعه إلى فرع آخر. لا تفترض أن الفرع الرئيسي هو main دائمًا؛ تحقق من إعداد المشروع. ينبغي أن يكون ذلك إصدارًا عاديًا للمشروع ومتفقًا عليه، من دون إضافة ملف أسرار إلى commit.

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

في Next.js شرط إضافي: تُستبدل الإشارات مثل process.env.NEXT_PUBLIC_RELEASE_LABEL بقيمها أثناء next build. وتثبت القيمة بعد البناء. لن تؤدي إعادة ضبط الإعداد من دون بناء جديد إلى إعادة كتابة شيفرة JavaScript على جانب العميل التي سبق إرسالها.

كيفية التحقق من النتيجة دون كشف المفتاح#

ابدأ بمثال آمن: تسمية غير سرية صراحةً باسم NEXT_PUBLIC_RELEASE_LABEL وقيمتها preview-check. هذان اسم ونص توضيحيان، وليسا مفتاحًا أو اختبارًا أُجري هنا. إذا قرأ تطبيق Next.js هذا المتغير مباشرةً عبر process.env.NEXT_PUBLIC_RELEASE_LABEL، فيمكنه عرض التسمية في الموضع المقصود من الواجهة بعد بناء جديد. لا يؤكد هذا الفحص سوى تمرير الإعداد العام.

يُتحقق من المفتاح الخاص بطريقة مختلفة. لا تعرض قيمته أو جزءًا منه أو طوله أو كامل process.env. ولا تنشئ عنوان URL عامًا يعيد محتويات المتغير. أولًا، تحقق فقط مما إذا كان الإعداد «موجودًا / غير موجود» على الخادم، ثم تحقق على نحو منفصل من دالة التطبيق التي تستخدم الخدمة. وجود الإعداد لا يثبت أن المفتاح صالح أو أنه يملك الأذونات المطلوبة.

يمكنك تسجيل النتائج من دون أسرار:

• يتطابق المشروع والبيئة والفرع مع الخيارات المحددة أثناء الإعداد؛
• تتحقق من عنوان URL لعملية نشر جديدة أُنشئت بعد حفظ المتغير؛
• اكتمل البناء ونُفذت دالة التطبيق المطلوبة باستخدام بيانات اختبار آمنة؛
• لم يُكشف السر في المتصفح أو استجابات API أو السجلات أو المحادثات.

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

ما الذي يجب التحقق منه إذا ظلت القيمة undefined#

تعني undefined أنه لم يتم الحصول على قيمة عند نقطة الوصول تلك. تحقّق من الاسم والبيئة والإصدار بهذا الترتيب، من دون تغيير جميع الإعدادات دفعة واحدة.

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

يتطلب الانتقال إلى خادمك الخاص إجراءً مختلفًا: راجع دليل نشر مشروع باستخدام Coolify. لا تنطبق أسماء أزرار Vercel وخطوات الإعداد فيها على Coolify.

انتقل إلى Ailoot.