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

> متغيرات البيئة، وDevelopment/Preview/Production، ونشر جديد، وكيفية التحقق من المفاتيح بأمان في Next.js دون تمريرها إلى المتصفح.

Source: https://ailoot.ai/blog/ar/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/ar/vercel-environment-variables/
Language: ar
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-9f603d588f51df19bf954f2e40ce2b9f7edb59a2bcc34258104d0bcf9b05ffca


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="أهم نقطة في هذا القسم">

النقطة الأساسية

إذا لم يكن ملف `.env` الذي يحتوي على أسرارك موجودًا في Git، فأضف المتغيرات المطلوبة في قسم **Environment Variables** ضمن مشروعك على Vercel. حدّد البيئة، واحفظ الإعدادات، وأنشئ عملية نشر جديدة: لن تتغير الإصدارات التي سبق نشرها. في Next.js، لا تضف البادئة `NEXT_PUBLIC_` إلى مفتاح سري، إذ ستُضمَّن قيمته في شيفرة المتصفح أثناء عملية البناء.

</div>

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



[تجد في الوثائق معلومات عملية حول استخدام Ailoot](https://ailoot.ai/docs/).

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

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

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

إذا كنت لا تزال غير متأكد مما يمكن تخزينه في ملفات المصدر، فابدأ بـ[فحص الأمان لمشروع أُنشئ باستخدام الذكاء الاصطناعي](https://ailoot.ai/blog/ar/vibe-coding-security/). أما هنا، فنتناول سؤالًا أضيق نطاقًا: أين تضبط إعدادات عملية نشر محددة على Vercel.

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

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

| ما يجب التحقق منه | الخيارات الممكنة | سبب الأهمية |
|----|----|----|
| بيئة Vercel | Development، Preview، Production | يجب أن ينطبق الإعداد على الإصدار الذي تتحقق منه |
| مكان قراءة المتغير | الخادم أو المتصفح | يجب ألا يُضمَّن مفتاح خاص في شيفرة جهة العميل |
| وقت قراءة المتغير | وقت البناء أو أثناء تنفيذ دالة الخادم | في Next.js، تُثبَّت القيم العامة أثناء البناء |

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

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

إذا لم تكن قد حددت إطار العمل بعد، فاطلب من الوكيل تحديده من ملفات المشروع. قد تساعدك [مقارنة Astro وNext.js](https://ailoot.ai/blog/ar/astro-vs-nextjs-for-ai-built-sites/) على فهم الفروق؛ ولا يمكنك تطبيق قاعدة `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` أنه لم يتم الحصول على قيمة عند نقطة الوصول تلك. تحقّق من الاسم والبيئة والإصدار بهذا الترتيب، من دون تغيير جميع الإعدادات دفعة واحدة.

| العَرَض | ما يجب التحقق منه |
|----|----|
| يعمل محليًا، لكنه لا يعمل في Preview | تحقق مما إذا كان الاسم موجودًا في إعدادات Preview للمشروع، وما إذا كان قد تم تحديد فرع آخر |
| يعمل Preview، لكن لا يعمل Production | تحقق مما إذا كان الاسم مضبوطًا لـ Production، وما إذا كان قد أُنشئ إصدار رئيسي جديد بعد Save |
| يتصرف أحد فروع Preview بطريقة مختلفة | تحقق مما إذا كانت هناك قيمة بالاسم نفسه مضبوطة لذلك الفرع وتتجاوز الإعداد العام |
| يرى الخادم المتغير، لكن المتصفح لا يراه | هذا متوقع في Next.js للمتغير غير العام؛ لا تنقل مفتاحًا خاصًا إلى المتصفح |
| ما زالت تسمية Next.js العامة تعرض قيمتها القديمة | تحقق مما إذا أُجري بناء جديد بالقيمة المطلوبة، وما إذا كان عنوان URL المفتوح يعود إلى عملية النشر تلك |
| الاسم العام صحيح، لكن الاستبدال لا يعمل | تحقق مما إذا كانت الشيفرة تقرأه ديناميكيًا عبر `process.env[varName]`؛ فـ Next.js لا يضمّن هذه الإشارات داخل الشيفرة |

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

يتطلب الانتقال إلى خادمك الخاص إجراءً مختلفًا: راجع [دليل نشر مشروع باستخدام Coolify](https://ailoot.ai/blog/ar/coolify-claude-code-deploy/). لا تنطبق أسماء أزرار Vercel وخطوات الإعداد فيها على Coolify.

<div class="section" role="doc-bibliography" aria-label="المصادر">

### المصادر

- [متغيرات البيئة في Vercel](https://vercel.com/docs/environment-variables)
- [إضافة متغيرات البيئة في Vercel وإدارتها](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [متغيرات البيئة في Next.js](https://nextjs.org/docs/app/guides/environment-variables)

</div>





[انتقل إلى Ailoot](https://ailoot.ai/).

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

### لماذا يبقى المتغير غير معرّف بعد حفظه في Vercel؟

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

### هل أضيف NEXT_PUBLIC_ لإظهار سر لتطبيق Next.js؟

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


## Ailoot · الشركة ومحفظة مشاريعها

تستند Ailoot إلى خبرة تشغيلية متراكمة وقاعدة عملاء واسعة وخدمة مستقرة ومراقبة مستمرة لمؤشرات الأداء KPI.

الشركة ومحفظة مشاريعها: ملايين العملاء؛ مبيعات بالمليارات شهريًا.

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