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

يمكنك إجراء اختبارات محلية لتطبيقك قبل نشره على 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 وابدأ تشغيلها كما هو موضّح في مقالة تثبيت "مجموعة أدوات المحاكاة المحلية" وضبطها ودمجها. بالإضافة إلى أي محاكيات أخرى في 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. يمكنك أيضًا ضبط محاكي App Hosting من خلال تعديل 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]

Where applicable, consider using test-only keys in apphosting.emulator.yaml that don't have access to production data, can't have global side effects (sending emails, charging credit cards), or have lower quotas. يساعد ذلك في ضمان أن يكون للرمز غير المراجَع عواقب أقل في العالم الحقيقي.

ننصحك باستخدام "مجموعات 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
    },
    ...
  }