باستخدام Extensions، يمكنك تثبيت الإضافات وإدارتها في بيئة محلية آمنة والتعرّف بشكل أفضل على إمكاناتها مع تقليل تكاليف الفوترة. يشغّل المحاكي وظائف الإضافة محليًا، بما في ذلك الوظائف التي يتم تشغيلها استجابةً لأحداث في الخلفية باستخدام المحاكيات الخاصة بـ Cloud Firestore وRealtime Database وCloud Storage for Firebase وAuthentication وPub/Sub، والوظائف التي يتم تشغيلها استجابةً لأحداث Eventarc والمضمّنة في Cloud Functions الإصدار 2.
اختيار مشروع على Firebase
يحاكي Firebase Local Emulator Suite المنتجات لمشروع واحد على Firebase.
لاختيار المشروع الذي تريد استخدامه، نفِّذ الأمر
firebase use في دليل العمل قبل بدء المحاكيات. أو يمكنك تمرير العلامة --project إلى كل أمر من أوامر المحاكي.
تتيح Local Emulator Suite محاكاة مشاريع Firebase الحقيقية ومشاريع العرض التوضيحي.
نوع المشروع
الميزات
الاستخدام مع المحاكيات
Real
مشروع Firebase حقيقي هو مشروع أنشأته وأعددته (على الأرجح من خلال Firebase وحدة التحكّم).
تحتوي المشاريع الحقيقية على موارد نشطة، مثل مثيلات قواعد البيانات أو حِزم التخزين أو الدوال أو أي موارد أخرى تم إعدادها لمشروع Firebase هذا.
عند العمل مع مشاريع Firebase حقيقية، يمكنك تشغيل المحاكيات لأي من المنتجات المتوافقة أو جميعها.
بالنسبة إلى أي منتجات لا تحاكيها، ستتفاعل تطبيقاتك ورموزك مع مورد نشط (مثال على قاعدة البيانات، وحزمة التخزين، والدالة، وما إلى ذلك).
تجريبي
لا يتضمّن مشروع Firebase التجريبي أي إعدادات حقيقية في Firebase، كما لا يتضمّن أي موارد مباشرة. ويمكن عادةً الوصول إلى هذه المشاريع من خلال دروس تطبيقية حول الترميز أو برامج تعليمية أخرى.
تبدأ أرقام تعريف المشاريع التجريبية بالبادئة demo-.
عند استخدام مشاريع Firebase التجريبية، تتفاعل تطبيقاتك ورموزك مع المحاكيات فقط. إذا حاول تطبيقك التفاعل مع أحد الموارد التي لم يتم تشغيل محاكي لها، سيتعذّر تنفيذ هذا الرمز.
ننصحك باستخدام المشاريع التجريبية كلما أمكن ذلك. تتضمّن المزايا ما يلي:
إعداد أسهل، إذ يمكنك تشغيل المحاكيات بدون إنشاء مشروع على Firebase
أمان أقوى، لأنه في حال استدعى الرمز عن طريق الخطأ موارد غير محاكية (إنتاج)، لن يكون هناك أي فرصة لتغيير البيانات أو استخدامها أو إصدار فواتير لها
إتاحة استخدام التطبيق بشكل أفضل بلا إنترنت، إذ لا حاجة إلى الاتصال بالإنترنت لتنزيل إعدادات حزمة SDK
تثبيت إحدى الإضافات وتقييمها
يمكنك بسهولة استخدام Extensions المحاكي لتقييم ما إذا كانت إحدى الإضافات تلبي احتياجاتك.
لنفترض أنّك مهتم بالإضافة "إرسال رسالة إلكترونية مشغّلة" (firestore-send-email)، مع أنّ سير العمل التالي يشمل أي إضافة. عند تشغيلها باستخدام المحاكيات المحلية، ستستفيد ميزة "إرسال رسائل إلكترونية مشغّلة" تلقائيًا من المحاكيَين Cloud Firestore وCloud Functions.
لتقييم إضافة على المستوى المحلي، اتّبِع الخطوات التالية:
أضِف الإضافة إلى بيان الإضافات المحلية. بيان الإضافات هو قائمة بمثيلات الإضافات وإعداداتها.
سيؤدي تنفيذ الأمر أعلاه إلى مطالبتك بضبط أحدث إصدار من إضافة
firebase/firestore-send-email وحفظ عملية الضبط في البيان، ولكن لن يتم نشر عملية الضبط في مشروعك. لمزيد من المعلومات حول هذا الموضوع، يُرجى الاطّلاع على إدارة إعدادات الإضافات باستخدام ملفات البيان.
ابدأ Local Emulator Suite كالمعتاد.
firebase emulators:start
الآن، باستخدام مثيل الإضافة firestore-send-email المُدرَج في ملف البيان، سيتمكّن Local Emulator Suite من تنزيل رمز المصدر الخاص بهذه الإضافة إلى ~/.cache/firebase/extensions. بعد تنزيل المصادر، سيبدأ Local Emulator Suite وستتمكّن من تشغيل أي من الوظائف التي يتم تشغيلها في الخلفية في الإضافة وربط تطبيقك بـ Local Emulator Suite لاختبار تكاملها مع تطبيقك.
يمكنك استخدام Emulator Suite UI لإضافة بيانات إلى مجموعة مستندات البريد الإلكتروني
وإعداد موارد أخرى في الخلفية، حسب ما تتطلّبه إضافة Trigger Email.
بدلاً من ذلك، بالنسبة إلى بيئات الاختبار غير التفاعلية، مثل سير عمل الدمج المستمر، يمكنك كتابة نص برمجي للاختبار لتقييم الإضافة، والذي يتضمّن، من بين خطوات أخرى، ملء بيانات Cloud Firestore اللازمة وتشغيل الدوال. بعد ذلك، يمكنك استدعاء Local Emulator Suite
لتنفيذ نص الاختبار:
firebaseemulators:execmy-test.sh
أوجه الاختلاف بين الاختبار باستخدام المحاكي Extensions وبيئة الإنتاج
يتيح لك محاكي Extensions اختبار الإضافات بطريقة تتطابق بشكل كبير مع تجربة الإصدار العلني. ومع ذلك، هناك بعض الاختلافات عن سلوك الإصدار العلني.
Cloud IAM
لا تحاول "مجموعة أدوات المحاكاة" من Firebase تكرار أي سلوك مرتبط بإدارة الهوية وإمكانية الوصول (IAM) أو الالتزام به عند التشغيل. تلتزم المحاكيات بقواعد أمان Firebase المقدَّمة، ولكن في الحالات التي يتم فيها استخدام "إدارة الهوية وإمكانية الوصول" عادةً، مثلاً لضبط حساب الخدمة الذي يستدعي Cloud Functions وبالتالي الأذونات، لا يمكن ضبط المحاكي وسيستخدم الحساب المتاح على مستوى العالم على جهاز المطوِّر، على غرار تشغيل نص برمجي محلي مباشرةً.
القيود المفروضة على نوع التشغيل
في الوقت الحالي، لا يتيح Firebase Local Emulator Suite سوى الوظائف التي يتم تشغيلها عند تلقّي طلب HTTP، ومشغّلات الأحداث المخصّصة في Eventarc للإضافات، والوظائف التي يتم تشغيلها عند وقوع حدث في الخلفية في Cloud Firestore وRealtime Database وCloud Storage for Firebase وAuthentication وPub/Sub. لتقييم الإضافات التي تستخدم أنواعًا أخرى من الدوال المشغَّلة، عليك تثبيت الإضافة في مشروع تجريبي على Firebase.
تاريخ التعديل الأخير: 2025-09-06 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-06 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["\u003cbr /\u003e\n\n| **Beta.** This emulator is currently in beta. It might be\n| changed in backward-incompatible ways. As always, feedback is greatly\n| appreciated. Let us know what you think!\n\nBefore using the Extensions emulator with your app, make sure that\nyou [understand the overall Firebase Local Emulator Suite workflow](/docs/emulator-suite/connect_and_prototype?database=Firestore),\nand that you [install and configure](/docs/emulator-suite/install_and_configure)\nthe Local Emulator Suite and review its [CLI commands](/docs/emulator-suite/install_and_configure#startup).\n\nThis guide also assumes you are familiar with [Firebase Extensions](/docs/extensions)\nand how to [use them in your Firebase apps](/docs/extensions/overview-use-extensions).\n\nWhat can I do with the Extensions emulator?\n\nWith the Extensions emulator, you can install and manage extensions in a\nsafe local environment and better understand their capabilities while minimizing\nbilling costs. The emulator runs your extension's functions locally, including\nbackground event-triggered functions using the emulators for\nCloud Firestore, Realtime Database, Cloud Storage for Firebase, Authentication and\nPub/Sub, and Eventarc-triggered functions implemented in\nCloud Functions v2.\n| **Note:** Some extensions may call Google Cloud APIs and access services for which emulators do not exists in the Local Emulator Suite. Running the extension will still access those live services and may result in billing costs. Be sure to review extension descriptions carefully before evaluating them, so you understand billing impacts. We recommend you create and use a demo project for running the Extensions emulator, as described next.\n\nChoose a Firebase project\n\nThe Firebase Local Emulator Suite emulates products for a single Firebase project.\n\nTo select the project to use, before you start the emulators, in the CLI run\n`firebase use` in your working directory. Or, you can pass\nthe `--project` flag to each emulator\ncommand.\n| **Note:** It's generally a good practice to use one project ID for all emulator invocations, so the Emulator Suite UI, different product emulators, and all running instances of a particular emulator can communicate correctly in all cases. In fact, by default, the Local Emulator Suite will warn on detecting multiple project IDs in use, though you can override this behavior. For guidance on setting and managing project IDs, see the [Installation and configuration guide](/docs/emulator-suite/install_and_configure#project_id_configuration).\n\nLocal Emulator Suite supports emulation of *real* Firebase projects and\n*demo* projects.\n\n| Project type | Features | Use with emulators |\n|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Real | A real Firebase project is one you created and configured (most likely via the Firebase console). Real projects have live resources, like database instances, storage buckets, functions, or any other resource you set up for that Firebase project. | When working with real Firebase projects, you can run emulators for any or all of the supported products. For any products you are not emulating, your apps and code will interact with the *live* resource (database instance, storage bucket, function, etc.). |\n| Demo | A demo Firebase project has no *real* Firebase configuration and no live resources. These projects are usually accessed via codelabs or other tutorials. Project IDs for demo projects have the `demo-` prefix. | When working with demo Firebase projects, your apps and code interact with emulators *only*. If your app attempts to interact with a resource for which an emulator isn't running, that code will fail. |\n\nWe recommend you use demo projects wherever possible. Benefits include:\n\n- Easier setup, since you can run the emulators without ever creating a Firebase project\n- Stronger safety, since if your code accidentally invokes non-emulated (production) resources, there is no chance of data change, usage and billing\n- Better offline support, since there is no need to access the internet to download your SDK configuration.\n\n| **Note:** If you want to emulate cross-service interactions such as database-triggered Cloud Functions or Rules that rely on Authentication you must make sure that the project ID in your code (in `initializeApp()`, etc.) matches the project ID used by the Firebase CLI.\n\nInstall and evaluate an extension\n\nUsing the Extensions emulator to evaluate whether an extension meets your\nneeds is straightforward.\n\nLet's assume you're interested in the Trigger Email\n(`firestore-send-email`) [extension](/docs/extensions/official/firestore-send-email),\nthough the following workflow covers any extension. When run with local emulators,\nTrigger Email will automatically make use of the Cloud Firestore and\nCloud Functions emulators.\n\nTo evaluate an extension locally:\n\n1. Add the extension to the local extensions manifest. An extensions manifest is\n a list of extension instances and their configurations.\n\n ```\n firebase ext:install --local firebase/firestore-send-email\n ```\n\n Running the above command will prompt you to configure the latest version of\n `firebase/firestore-send-email` extension and save the configuration to\n the manifest, but it won't deploy the configuration to your project. For\n more about this, see [Manage extensions configuration with manifests](/docs/extensions/manifest)\n2. Start the Local Emulator Suite as you would normally.\n\n ```\n firebase emulators:start\n ```\n\nNow, using the `firestore-send-email` extension instance listed in\nyour manifest, the Local Emulator Suite will download the source code of\nthat extension to `~/.cache/firebase/extensions`. Once soures have been\ndownloaded, the Local Emulator Suite will start and you'll be able to\ntrigger any of the extension's background triggered functions and connect your\napp to the Local Emulator Suite to test their integration with your app.\n\nYou can use Emulator Suite UI to add data to the email documents collection\nand set up other backend resources, as required by the Trigger Email extension.\n\nAlternatively, for non-interactive testing environments like continuous\nintegration workflows, you can write a test script for evaluating the extension\nthat, among other steps, populates necessary Cloud Firestore data and\ntriggers functions. You would then invoke the Local Emulator Suite\nto execute your test script: \n\n firebase emulators:exec my-test.sh\n\n| **Note:** You can use the Extensions emulator to evaluate extensions that publish custom events. The Extensions emulator works together with the Cloud Functions emulator to help you test custom event-handling functions you implement with Cloud Functions v2 code. See [Connect your app to the Cloud Functions Emulator](/docs/emulator-suite/connect_functions).\n\nHow testing with the Extensions emulator differs from production\n\nThe Extensions emulator lets you test extensions in a way that closely\nmatches the production experience. However, there are some differences from\nproduction behavior.\n\nCloud IAM\n\nThe Firebase Emulator Suite does not attempt to replicate or respect any\nIAM-related behavior for running. Emulators adhere to the Firebase Security\nRules provided, but in situations where IAM would normally be used, for example\nto set Cloud Functions invoking service account and thus permissions, the\nemulator is not configurable and will use the globally-available account on\nyour developer machine, similar to running a local script directly.\n\nTriggering type limitation\n\nCurrently, the Firebase Local Emulator Suite only supports HTTP request-triggered\nfunctions, Eventarc custom event triggers for extensions, and background\nevent-triggered functions for Cloud Firestore, Realtime Database,\nCloud Storage for Firebase, Authentication and Pub/Sub. To evaluate extensions\nthat use other types of triggered functions, you need to\n[install your extension](/docs/extensions/install-extensions)\nin a test Firebase project.\n\nWhat next?\n\n- For a curated set of videos and detailed how-to examples, follow the [Firebase Emulators Training Playlist](/learn/pathways/firebase-emulators)."]]
