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

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

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

يفترض هذا الموضوع أنّك على دراية بخدمة 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 وإعدادها ودمجها. بالإضافة إلى أي محاكيات Firebase أخرى تريد إعدادها، تأكَّد من اختيار App Hosting Emulator. تطلب منك واجهة سطر الأوامر (CLI) بعض قيم المحاكي 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 مباشرةً. مخطط محاكي App Hosting هو:

{
  ...
  "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

إعداد الأمر start لتطبيقات Angular

إذا انتهت مهلة الأمر start للمحاكي، من المحتمل أنّ خادم تطوير Angular يعرض تطبيقك على منفذ مختلف عن المنفذ الذي يتوقّعه App Hosting المحاكي. يمكنك حلّ هذه المشكلة من خلال إضافة بعض الإعدادات الإضافية في firebase.json:

• اضبط emulators.apphosting.startCommand على ng serve.
• لاستخدام منفذ غير تلقائي، اضبطه باستخدام emulators.apphosting.port (بدلاً من إضافة العلامة --port إلى ng serve في emulators.apphosting.startCommand).

على سبيل المثال:

"emulators": {
    "apphosting": {
      "port": 5002,
      "rootDirectory": "./test-app",
      "startCommand": "ng serve"
    },
    "ui": {
      "enabled": true
    },
    ...
  }