將應用程式連線至 Cloud Firestore 模擬器

將應用程式連線至 Cloud Firestore 模擬器之前，請務必瞭解整體 Firebase 本機模擬器套件的工作流程，並安裝及設定本機模擬器套件並查看其 CLI 指令。

選擇 Firebase 專案

Firebase 本機模擬器套件可模擬單一 Firebase 專案中的產品。

如要選取要使用的專案，請先透過 CLI 在工作目錄中執行 firebase use，再啟動模擬器。或者，您也可以將 --project 標記傳遞至每個模擬器指令。

注意： 一般來說，建議您針對所有模擬器叫用使用單一專案 ID，如此一來，模擬器套件 UI、不同的產品模擬器，以及特定模擬器執行的所有執行個體都能在所有情況下正確通訊。事實上，本機模擬器套件預設會在偵測到使用中的多個專案 ID 時發出警告，但您可以覆寫這項行為。如需設定及管理專案 ID 的指南，請參閱安裝和設定指南。

本機模擬器套件支援模擬「實際」的 Firebase 專案和示範專案。

專案類型	功能與特色	與模擬器搭配使用
真實	真正的 Firebase 專案是您建立及設定的專案 (很有可能透過 Firebase 控制台進行)。 真實專案包含使用中的資源，例如資料庫執行個體、儲存空間值區、函式，或是您為該 Firebase 專案設定的任何其他資源。	使用實際的 Firebase 專案時，您可以針對任何或所有支援的產品執行模擬器。 針對並非您要模擬的任何產品，應用程式和程式碼會與即時資源 (資料庫執行個體、儲存空間值區、函式等) 互動。
示範	示範 Firebase 專案沒有實際的 Firebase 設定，也沒有即時資源。一般來說，您可以透過程式碼研究室或其他教學課程存取這些專案。 示範專案的專案 ID 含有 demo- 前置字串。	使用示範 Firebase 專案時，您的應用程式和程式碼「只會」與模擬器互動。如果應用程式嘗試與未執行模擬器的資源互動，該程式碼將會失敗。

建議您盡可能使用示範專案。Meet 具備以下優點：

• 設定更簡單，因為您無須建立 Firebase 專案即可執行模擬器
• 安全性較高，因為如果程式碼意外叫用非模擬的 (正式環境) 資源，就無法變更資料、使用及計費
• 改善離線支援功能，因為不需透過網際網路即可下載 SDK 設定。

注意： 如要模擬跨服務的互動，例如資料庫觸發的 Cloud Functions 或需要驗證的規則，請確保程式碼中的專案 ID (位於 initializeApp() 等) 與 Firebase CLI 使用的專案 ID 相符。

檢測應用程式，以便與模擬器通訊

啟動時，Cloud Firestore 模擬器會為 firebase.json 檔案中的每個 firestore 設定建立預設資料庫和具名資料庫。

此外，系統也會以隱含方式建立已命名資料庫，以回應對參照特定資料庫的模擬器的任何 SDK 或 REST API 呼叫。這類隱含的資料庫會以開放規則運作。

如要在模擬器套件 UI 中以互動方式使用預設和已命名的資料庫，請在瀏覽器的網址列中更新網址，以選取預設或已命名的資料庫。

• 舉例來說，如要瀏覽預設執行個體中的資料，請將網址更新為 localhost:4000/firestore/default/data
• 如要瀏覽名為 ecommerce 的執行個體，請更新至 localhost:4000/firestore/ecommerce/data。

Android、Apple 平台和 Web SDK

設定應用程式內設定或測試類別，以與 Cloud Firestore 互動，如下所示。請注意，在以下範例中，應用程式程式碼會連線至預設的專案資料庫。如需使用預設資料庫以外其他 Cloud Firestore 資料庫的範例，請參閱多個資料庫指南。

注意： Cloud Firestore 模擬器會在關機時清除資料庫內容。由於 Firestore SDK 的離線快取不會自動清除，因此建議您在模擬器設定中停用本機永久性，以免模擬資料庫和本機快取之間出現差異。在 Web SDK 中，系統預設會停用保留功能。

Kotlin+KTX

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
EmulatorSuite.kt

Java

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
EmulatorSuite.java

Swift

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

Web

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

如要透過模擬器測試 Firestore 事件觸發的 Cloud Functions，您不需要進行額外設定。當 Firestore 和 Cloud Functions 模擬器同時執行時，它們會自動搭配運作。

管理員 SDK

設定 FIRESTORE_EMULATOR_HOST 環境變數時，Firebase Admin SDK 會自動連線至 Cloud Firestore 模擬器：

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

如果程式碼是在 Cloud Functions 模擬器中執行，系統會在呼叫 initializeApp 時自動設定專案 ID 和其他設定。

如要讓 Admin SDK 程式碼連線至在其他環境中執行的共用模擬器，您必須指定使用 Firebase CLI 設定的相同專案 ID。您可以將專案 ID 直接傳遞至 initializeApp，或是設定 GCLOUD_PROJECT 環境變數。

Node.js Admin SDK

admin.initializeApp({ projectId: "your-project-id" });

環境變數

export GCLOUD_PROJECT="your-project-id"

清除測試之間的資料庫

Production Firestore 不提供清除資料庫的平台 SDK 方法，但 Firestore 模擬器會提供此用途專用的 REST 端點，您可以在測試開始之前，從測試架構設定/tearDown 步驟、從測試類別或殼層 (例如，使用 curl) 呼叫這個端點。您可以使用這個方法做為直接關閉模擬器程序的替代方案。

在適當的方法中，執行 HTTP DELETE 作業，將 Firebase 專案 ID (例如 firestore-emulator-example) 提供給下列端點：

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

當然，您的程式碼應等待 REST 確認，確認清除完畢或失敗。

您可以透過殼層執行此作業：

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

完成像這樣的實作步驟後，您可以排出測試順序並觸發函式，確信舊資料會在執行期間遭到清除，且使用的是新的基準測試設定。

匯入及匯出資料

資料庫和 Cloud Storage for Firebase 模擬器可讓您從執行中的模擬器執行個體匯出資料。定義要在單元測試或持續整合工作流程中使用的基準資料集，然後匯出供團隊成員共用。

firebase emulators:export ./dir

在測試中，在模擬器啟動時匯入基準資料。

firebase emulators:start --import=./dir

您可以指示模擬器在關機時匯出資料，方法是指定匯出路徑，或者直接使用傳遞至 --import 標記的路徑。

firebase emulators:start --import=./dir --export-on-exit

這些資料匯入和匯出選項也適用於 firebase emulators:exec 指令。詳情請參閱模擬器指令參考資料。

以圖表呈現安全性規則活動

處理原型和測試迴圈時，您可以使用本機模擬器套件提供的視覺化工具和報表。

使用要求監控器

Cloud Firestore 模擬器可讓您在模擬器套件 UI 中，以視覺化方式呈現用戶端要求，包括 Firebase 安全性規則的評估追蹤記錄。

開啟「Firestore」>「Request」分頁，查看每項要求的詳細評估序列。

以視覺化方式呈現規則評估報表

將安全性規則新增至原型後，即可使用本機模擬器套件偵錯工具進行偵錯。

執行一系列的測試後，您可以存取測試涵蓋範圍報表，瞭解每個安全性規則的評估方式。

如要取得報告，請在模擬器執行時查詢已公開的端點。如果是適用於瀏覽器的版本，請使用下列網址：

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

這會將規則分為不同的運算式和子運算式，您可以將滑鼠遊標移到運算式和子運算式上，以便查看更多資訊，包括傳回的評估次數和值。針對這項資料的原始 JSON 版本，請在查詢中加入以下網址：

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

這裡的 HTML 版本報表會醒目顯示含有未定義和空值錯誤的評估資料：

Cloud Firestore 模擬器與實際工作環境的差異

Cloud Firestore 模擬器會嘗試確實複製實際工作環境服務的行為，但有一些明顯的限制。

Cloud Firestore 支援多個資料庫

目前，模擬器套件 UI 支援預設資料庫的互動式建立、編輯、刪除、要求監控和安全性視覺化功能，但不支援其他已命名的資料庫。

不過，模擬器本身會根據 firebase.json 檔案中的設定建立具名資料庫，並以隱含方式回應 SDK 或 REST API 呼叫。

交易

模擬器目前不會實作實際工作環境中的所有交易行為。如果測試在單一文件中執行多次並行寫入的功能，模擬器完成寫入要求的速度可能會比較慢。在某些情況下，鎖定功能最多可能需要 30 秒才會釋出。視需要調整測試逾時。

索引

模擬器不會追蹤複合索引，而是執行任何有效的查詢。請務必針對實際的 Cloud Firestore 執行個體測試應用程式，以判斷所需的索引。

限制

模擬器不會強制執行在實際工作環境中強制執行的所有限制。舉例來說，模擬器可能會允許因實際工作環境服務拒絕而遭到拒絕的交易。請務必熟悉記錄的限制，並設計應用程式來主動避開這些限制。

接下來呢？

• 如需一系列精選影片和詳細教學範例，請參閱 Firebase 模擬器訓練播放清單。
• 調查涉及安全性規則測試和 Firebase Test SDK 的進階用途：測試安全性規則 (Firestore)。
• 由於觸發的函式是與 Cloud Firestore 的一般整合，因此請參閱在本機執行函式一文，進一步瞭解 Cloud Functions for Firebase 模擬器。