اختبار عملية نشر تطبيقك محليًا

يمكنك إجراء اختبارات محلية لتطبيقك قبل App Hosting نشره باستخدام App Hosting المحاكي، وهو جزء من مجموعة أدوات المحاكاة المحلية لمنصة Firebase.

قبل استخدام محاكي App Hosting، تأكَّد من أنّك تفهم سير العمل العام في Local Emulator Suite على Firebase، وأنّك ثبّتَ Local Emulator Suite وضبطته وراجعت أوامر واجهة سطر الأوامر الخاصة به.

يفترض هذا الموضوع أنّك على دراية بـ App Hosting. إذا لزم الأمر، راجِع App Hosting مقدمة والمواد الأخرى لمساعدتك في فهم طريقة عمل App Hosting.

ما الذي يمكنني فعله باستخدام محاكي App Hosting؟

يتيح لك المحاكي App Hosting اختبار تطبيقات الويب وتحسينها محليًا. يمكن أن يؤدي ذلك إلى تبسيط عملية التطوير وتحسين جودة تطبيقات الويب التي تم إنشاؤها باستخدام Firebase ونشرها على App Hosting.

يوفّر App Hosting المحاكي ما يلي:

1. تتيح لك تشغيل تطبيق الويب على جهازك، مع تحديد متغيّرات البيئة والأسرار في ملفات إعداد apphosting.yaml.
2. يمكن إلغاء المتغيرات السرية ومتغيرات البيئة لاستخدامها في المحاكي باستخدام الملف apphosting.emulator.yaml.
3. يمكن استخدامه مع محاكيات Firebase الأخرى. إذا كنت تستخدم Firestore أو Auth أو أي محاكي آخر، يضمن Local Emulator Suite أن يتم تشغيل هذه المحاكيات أولاً قبل محاكي App Hosting.

ضبط المحاكي

للبدء، ثبِّت Local Emulator Suite وأعِد تهيئته كما هو موضح في تثبيت Local Emulator Suite وإعداده ودمجه. بالإضافة إلى أي محاكيات أخرى من Firebase تريد إعدادها، احرص على اختيار App Hosting Emulator. سيطلب منك واجهة سطر الأوامر إدخال بعض App Hosting قيم المحاكي، بما في ذلك:

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

firebase init emulators
=== Emulators Setup
? Which Firebase emulators do you want to set up? Press Space to select emulators, then Enter to confirm your choices. (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ App Hosting Emulator
 ◯ Firestore Emulator
 ◯ Database Emulator
 ◯ Hosting Emulator
 ◯ Pub/Sub Emulator
 ◯ Storage Emulator
 ◯ Eventarc Emulator
(Move up and down to reveal more choices)

? Specify your app's root directory relative to your project (./)

? The App Hosting emulator uses a file called apphosting.emulator.yaml to
override values in apphosting.yaml for local testing. This codebase does not
have one, would you like to create it? (Y/n)

? Which environment variables would you like to override? (Press <space> to
select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ MEMCACHE_ADDR
 ◯ API_KEY

? What new value would you like for plaintext MEMCACHE_ADDR?

? What would you like to name the secret reference for API_KEY? (test-api-key)

? What new value would you like for secret TESTKEY [input is hidden]? [input is hidden]

? Your config has secret values. Please provide a comma-separated list of users
or groups who should have access to secrets for local development:

✔  Successfully set IAM bindings on secret test-api-key.

تُستخدَم أي قيم تقدّمها في مسار الإعداد هذا لتعديل App Hosting إعداد المحاكي في firebase.json. يمكنك أيضًا إعداد محاكي "استضافة التطبيقات" من خلال تعديل firebase.json مباشرةً. في ما يلي مخطط المحاكي الخاص بميزة "استضافة التطبيقات":

{
  ...
  "emulators": {
    "apphosting": {
      "startCommand": <command> [optional]
      "rootDirectory": <path> [optional]
      }
    }
  }

• يتم إنشاء startCommand وضبطه تلقائيًا عند تهيئة المحاكي. في حال عدم توفيرها، سيكتشف المحاكي أمر التطوير الخاص بمدير الحِزم ويشغّله.
• يُستخدَم rootDirectory لدعم عمليات إعداد المشاريع التي تستخدم مستودعًا واحدًا. إذا كان تطبيقك على الويب في دليل فرعي، عليك تقديم مسار هذا الدليل بالنسبة إلى الجذر (موقع firebase.json).

إدارة المحاكاة

يؤدي إعداد المحاكي إلى إنشاء ملف apphosting.emulator.yaml في الدليل الجذر لتطبيقك. يحتوي ملف الإعداد هذا على المخطط نفسه الخاص بملف apphosting.yaml المستخدَم في مرحلة الإنتاج، ولكنّه مخصّص حصريًا للتطوير المحلي. يقرأ المحاكي الإعدادات تلقائيًا من ملف apphosting.yaml، ولكن في حال توفّر ملف apphosting.emulator.yaml، يتم منح الأولوية للإعدادات الواردة في هذا الملف.

تم تصميم ملف apphosting.emulator.yaml ليكون آمنًا عند إرساله ومشاركته مع الزملاء. للمساعدة في ضمان عدم إرسال بيانات حساسة عن طريق الخطأ إلى مستودعات المصدر، يجب أن يكون أي متغير بيئة عبارة عن سر في apphosting.yaml، كما يجب أن يكون سرًا في apphosting.emulator.yaml. إذا لم يكن من الضروري تغيير قيمة سرية بين بيئة الإنتاج وبيئة التطوير المحلية (مثل مفتاح Gemini API)، ليس من الضروري إضافتها إلى apphosting.emulator.yaml، بل يجب منح فريقك إذن الوصول إلى القيمة السرية.

إذا كان تطبيقك يستخدم العديد من الأسرار (على سبيل المثال، مفاتيح واجهة برمجة التطبيقات لثلاث خدمات مختلفة، مع قيم مختلفة لكل من الإنتاج والتجهيز والتطوير المحلي)، قد تتجاوز الحد المجاني في Cloud Secret Manager وتدفع 0.06 دولار أمريكي لكل سر إضافي شهريًا. إذا كنت تفضّل إدارة الإعدادات المحلية خارج نظام التحكّم بالمصادر لتجنُّب هذه الرسوم، يمكنك استخدام ملف apphosting.local.yaml القديم. على عكس apphosting.emulator.yaml، يُسمح لهذا الملف بتقديم قيم نصية عادية لمتغيرات البيئة التي تمثّل قيمًا سرية في apphosting.yaml.

تنبيه: يجب عدم إرسال ملف apphosting.local.yaml إلى مستودع الرمز المصدر، لأنّ الملف قد يحتوي على قيم سرية بنص عادي.

منح المستخدمين أو المجموعات إذن الوصول إلى الأسرار

تتم قراءة الأسرار المخزّنة في apphosting.emulator.yaml عند بدء تشغيل المحاكي. وهذا يعني أنّ فريق التطوير يحتاج إلى إذن الوصول إلى المفتاح السري. يمكنك استخدام الأمر apphosting:secrets:grantaccess لمنح إذن الوصول إلى سرّ لمستخدم أو مجموعة من خلال البريد الإلكتروني.

firebase apphosting:secrets:grantaccess test-api-key --emails [e-mail]

عند الاقتضاء، ننصحك باستخدام مفاتيح مخصّصة للاختبار فقط في apphosting.emulator.yaml لا يمكنها الوصول إلى بيانات الإنتاج، ولا يمكن أن يكون لها آثار جانبية عامة (مثل إرسال رسائل إلكترونية أو تحصيل رسوم من بطاقات الائتمان)، و/أو لها حصص أقل. ويساعد ذلك في ضمان أن يكون للرموز البرمجية التي لم تتم مراجعتها تأثيرات أقل في العالم الحقيقي.

ننصحك باستخدام "مجموعات Google" لإدارة إذن الوصول إلى الأسرار بدلاً من منح إذن الوصول إلى مستخدمين فرديين. سيؤدي ذلك إلى تبسيط عملية إعداد أعضاء جدد في فريق المطوّرين، لأنّ إضافتهم إلى المجموعة سيمنحهم إذن الوصول إلى جميع الأسرار التي يحتاجون إليها. قد تكون لديك مجموعة مناسبة يتواصل فيها المطوّرون مع بعضهم. يساعد التحكّم في الوصول من خلال "مجموعات Google" أيضًا في ضمان فقدان المطوّرين الذين يغادرون فريقك إذن الوصول إلى جميع الأسرار عند إزالتهم من مجموعة البريد الإلكتروني. إذا كان السرّ يتيح الوصول إلى بيانات الإنتاج أو يسبب آثارًا جانبية في العالم الحقيقي، قد يظل من المناسب تدوير المفتاح ومنحه قيمة جديدة باستخدام firebase apphosting:secrets:set.

تشغيل المحاكي

firebase emulators:start

سيؤدي ذلك إلى بدء تشغيل جميع المحاكيات المحدّدة في ملف firebase.json، بما في ذلك المحاكي App Hosting.