متغيرات VITE_ مكشوفة للزوار: لا تضع مفاتيحك السرية في الواجهة
باختصار: إذا كان موقع متجرك أو لوحة الحجز مبنياً بـ Vite (وغالباً مع React أو Vue)، فكل متغير يبدأ اسمه بـ VITE_ يُدمج داخل ملفات JavaScript التي يحمّلها أي زائر. توثيق Vite نفسه يقول إن هذه المتغيرات يجب ألا تحتوي معلومات حساسة مثل مفاتيح API، لأن قيمها تُضمّن في الكود وقت البناء. إذا وضع المطور مفتاح خدمة رسائل أو مفتاح قاعدة بيانات أو كلمة مرور في متغير VITE_، فاعتبره مكشوفاً: انقله إلى الخادم، وأصدر مفتاحاً جديداً، وألغِ القديم.
لماذا يهمك هذا كصاحب عمل؟
تخيل شركة توصيل صغيرة في عمّان طلبت لوحة تحكم تعرض الطلبات وترسل رسائل نصية للزبائن. المطور أراد إنجاز العمل بسرعة، فوضع مفتاح مزود الرسائل في ملف .env باسم VITE_SMS_KEY، وجعل الواجهة تتصل بمزود الرسائل مباشرة من المتصفح. كل شيء يعمل، والتسليم تم في وقته.
المشكلة أن أي شخص يفتح الموقع، ثم يفتح أدوات المطور في المتصفح ويبحث في ملفات JavaScript، يستطيع أن يجد المفتاح. وبهذا المفتاح قد يرسل رسائل على حسابك، أو يقرأ بيانات لا يجب أن يراها. أنت لا تحتاج أن تعرف البرمجة لتفهم الخطر: أي شيء يصل إلى متصفح الزائر لم يعد سراً.
هذا مثال توضيحي، وليس حادثة حقيقية.
ما الذي يقوله توثيق Vite بالضبط؟
التوثيق الرسمي يشرح ثلاث نقاط أساسية:
- Vite يعرض متغيرات البيئة داخل كائن اسمه import.meta.env، والمتغيرات التي تبدأ بالبادئة VITE_ تُكشف في كود جهة المتصفح بعد البناء.
- هذه الثوابت تُستبدل بقيمها بشكل ثابت وقت البناء. أي أن القيمة نفسها تُكتب داخل الملف النهائي، لا اسم المتغير.
- لمنع تسريب المتغيرات بالخطأ، تجنب استخدام هذه البادئة لأي شيء سري. ويضرب التوثيق مثالاً: متغير VITE_SOME_KEY يظهر للكود، بينما DB_PASSWORD يبقى غير معرّف في الواجهة لأنه بلا بادئة.
ويقول التوثيق صراحة إن متغيرات VITE_ يجب ألا تحتوي معلومات حساسة مثل مفاتيح API، ويقترح للنشر الفعلي استخدام خادم خلفي أو دوال خادمية لحماية الأسرار بشكل صحيح.
سوء فهم شائع: «الملف مخفي، إذن المفتاح آمن»
كثير من المطورين المبتدئين يظنون أن وضع المفتاح في ملف .env يجعله آمناً لأن الملف لا يُرفع إلى المستودع. هذا صحيح فقط لنصف القصة. التوثيق يذكر أن ملفات .env.local و.env.[mode].local محلية ويُفترض إضافتها إلى .gitignore حتى لا تُحفظ في Git. هذا يحمي المفتاح من الظهور في المستودع، لكنه لا يحميه من الظهور في الموقع. إذا كان الاسم يبدأ بـ VITE_، فالقيمة ستُكتب في ملفات JavaScript التي يحمّلها الزائر بغض النظر عن مكان الملف.
كيف تتحقق بنفسك خلال دقائق؟
لا تحتاج أن تقرأ الكود كله. اطلب من المطور أو من شخص تقني تثق به هذه الخطوات:
- افتح ملف .env أو إعدادات البيئة في خدمة الاستضافة، واكتب قائمة بكل متغير يبدأ بـ VITE_.
- لكل متغير، اسأل سؤالاً واحداً: لو رآه أي زائر، هل تحدث مشكلة؟
- عنوان API عام، أو اسم الفرع، أو رقم واتساب العمل، أو مفتاح عام مصمم أصلاً للاستخدام في المتصفح مع قيود على النطاق: هذه عادة مقبولة.
- مفتاح مزود رسائل، كلمة مرور قاعدة بيانات، مفتاح سري لخدمة دفع أو بريد، رمز وصول لحساب إداري: هذه يجب ألا تكون هنا أبداً.
- ابحث في ملفات الموقع المنشورة عن أول بضعة أحرف من كل قيمة مشبوهة. إذا وجدتها، فالمفتاح مكشوف فعلاً.
انتبه لملفات الأوضاع المختلفة
التوثيق يشرح أن Vite يحمّل ملفات مختلفة حسب الوضع: ملف .env يُحمّل في كل الحالات، وملف .env.[mode] يُحمّل فقط في الوضع المحدد، مثل وضع الإنتاج. هذا يعني أن المراجعة يجب أن تشمل كل هذه الملفات، لا ملف التطوير وحده. قد يكون ملف التطوير نظيفاً، بينما ملف الإنتاج فيه مفتاح حقيقي بالبادئة VITE_ أضيف على عجل قبل الإطلاق. وراجع أيضاً متغيرات البيئة المعرفة في لوحة خدمة الاستضافة، لأنها تُقرأ وقت البناء بنفس الطريقة.
الإصلاح الصحيح: الخادم يتكلم مع الخدمة، لا المتصفح
الحل ليس تغيير اسم المتغير فقط. إذا أزلت البادئة فلن تعمل الواجهة، لأن المتصفح كان يحتاج المفتاح ليتصل بالخدمة مباشرة. المطلوب تغيير مسار الطلب:
- الواجهة ترسل طلباً إلى خادمك أو إلى دالة خادمية: «أرسل رسالة للطلب رقم كذا».
- الخادم يتحقق أن المستخدم مسجل الدخول وله صلاحية.
- الخادم يستخدم المفتاح السري المخزن عنده فقط، ويتصل بمزود الخدمة.
- الواجهة لا ترى المفتاح أبداً.
هذا ما يقصده التوثيق عندما يقترح خادماً خلفياً أو دوال خادمية لحماية الأسرار.
إذا كان المفتاح قد كُشف بالفعل
لا تكتفِ بنقل المفتاح. اعتبر أن أي مفتاح ظهر في موقع منشور قد يكون نُسخ من قبل:
- أصدر مفتاحاً جديداً من لوحة الخدمة المعنية.
- ألغِ المفتاح القديم بعد التأكد أن الخادم يعمل بالمفتاح الجديد.
- راجع سجلات الاستخدام في لوحة الخدمة لأي نشاط غير معتاد في الفترة الماضية.
- ضع قيوداً على المفتاح الجديد إذا كانت الخدمة تسمح، مثل تحديد النطاق أو عنوان الخادم أو الصلاحيات المسموحة.
- احذف المفتاح من أي نسخة قديمة من الموقع ما زالت منشورة، مثل نسخة تجريبية على رابط مؤقت.
قواعد بسيطة لفريقك من الآن
- كل متغير بالبادئة VITE_ يُعامل كمعلومة عامة، وكأنه مكتوب في صفحة الموقع.
- الأسرار تعيش في إعدادات الخادم فقط، ولا تمر بالواجهة.
- ملفات .env المحلية تُضاف إلى .gitignore كما يوصي التوثيق، لكن هذا لا يغني عن القاعدة الأولى.
- عند استلام مشروع من مطور خارجي، اطلب قائمة بكل المتغيرات ومعنى كل منها، وأين تُستخدم.
- إذا أراد المطور تغيير البادئة نفسها، فهناك خيار اسمه envPrefix في Vite، لكن تغيير الاسم لا يغير الحقيقة: ما يصل إلى الواجهة يصبح عاماً.
ماذا عن أطر العمل الأخرى؟
الفكرة نفسها موجودة في أدوات بناء أخرى بأسماء بادئات مختلفة. القاعدة العامة لا تتغير: أي قيمة تُدمج في كود المتصفح يمكن لأي زائر قراءتها. إذا لم تكن متأكداً من أداة مشروعك، اسأل المطور سؤالاً مباشراً: «هل يصل هذا المفتاح إلى متصفح الزائر؟» وانتظر جواباً واضحاً.
أسئلة شائعة
هل المتغير اللي بيبلش بـ VITE_ بيبين للزوار؟
نعم. بحسب توثيق Vite، المتغيرات بهذه البادئة تُكشف في كود جهة المتصفح بعد البناء.
إذا ما رفعت ملف .env على GitHub، بكون المفتاح آمن؟
لا. هذا يحمي المستودع فقط. القيمة تُكتب في ملفات الموقع المنشورة إذا كان اسم المتغير يبدأ بـ VITE_.
شو أعمل إذا لقيت مفتاح سري بالموقع؟
انقله إلى الخادم، وأصدر مفتاحاً جديداً، وألغِ القديم، وراجع سجلات الاستخدام في الخدمة.
هل كل المفاتيح في الواجهة خطيرة؟
لا. بعض المفاتيح مصممة لتكون عامة وتعمل مع قيود على النطاق. الخطر في المفاتيح السرية التي تعطي صلاحيات.
إذا استلمت موقعاً مبنياً بـ Vite ولا تعرف ما يظهر منه للزوار، اكتب لنا ونراجع متغيراته معك.