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

將應用程式連結至 Cloud Functions 模擬器之前，請務必瞭解 Firebase Local Emulator Suite 的整體工作流程，並安裝及設定 Local Emulator Suite，以及查看其 CLI 指令。

選擇 Firebase 專案

Firebase Local Emulator Suite 會模擬單一 Firebase 專案的產品。

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

Local Emulator Suite 支援模擬「實際」Firebase 專案和「示範」專案。

專案類型 功能 搭配模擬器使用
實數

實際的 Firebase 專案是指您建立及設定的專案 (通常是透過 Firebase 控制台)。

實際專案含有實際資源，例如資料庫執行個體、Storage bucket、函式，或您為該 Firebase 專案設定的其他資源。

使用實際的 Firebase 專案時，您可以為任何或所有支援的產品執行模擬器。

對於未模擬的產品，應用程式和程式碼會與實際資源 (資料庫執行個體、儲存空間 bucket、函式等) 互動。
示範

Firebase 示範專案沒有「實際」Firebase 設定，也沒有任何實際資源。這類專案通常可透過程式碼實驗室或其他教學課程存取。

示範專案的專案 ID 具有 demo- 前置字元。

使用 Firebase 示範專案時，應用程式和程式碼「只會」與模擬器互動。如果應用程式嘗試與未執行模擬器的資源互動，該程式碼就會失敗。

建議您盡可能使用試用專案。包括以下優點：

  • 設定更簡單，因為您不必建立 Firebase 專案，就能執行模擬器
  • 安全性更高，因為如果程式碼不小心叫用非模擬 (正式環境) 資源，就不會發生資料變更、用量和計費
  • 離線支援更完善，因為不需要連上網際網路，就能下載 SDK 設定。

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

檢測應用程式的可呼叫函式

如果原型和測試活動涉及可呼叫的後端函式，請按照下列方式設定與 Cloud Functions for Firebase 模擬器的互動：

Kotlin
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
Swift
Functions.functions().useEmulator(withHost: "localhost", port: 5001)
Unity
FirebaseFunctions functions = FirebaseFunctions.DefaultInstance;
// Connects to the Functions Emulator running on port 5001
functions.UseFunctionsEmulator("http://127.0.0.1:5001");

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);

Web

firebase.functions().useEmulator("127.0.0.1", 5001);

檢測應用程式，以便模擬 HTTPS 函式

程式碼中的每個 HTTPS 函式都會透過本機模擬器提供，網址格式如下：

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

舉例來說，如果 helloWorld 函式很簡單，且使用預設的主機通訊埠和區域，則會透過以下網址提供：

https://localhost:5001/$PROJECT/us-central1/helloWorld

檢測應用程式，模擬工作佇列函式

模擬器會根據觸發條件定義，自動設定模擬的工作佇列。如果 Admin SDK 偵測到模擬器是透過 CLOUD_TASKS_EMULATOR_HOST 環境變數執行，就會將佇列中的要求重新導向至模擬器。

請注意，正式環境中使用的調度系統比模擬器中實作的系統更複雜，因此模擬行為不一定會精確反映正式環境。模擬器中的參數會提供工作調度和重試頻率的上限。

檢測應用程式，模擬背景觸發的函式

Cloud Functions 模擬器支援下列來源的背景觸發函式：

  • Realtime Database 模擬器
  • Cloud Firestore 模擬器
  • Authentication 模擬器
  • Pub/Sub 模擬器
  • Firebase 快訊模擬器

如要觸發背景事件，請使用 Emulator Suite UI 修改後端資源，或使用平台 SDK 將應用程式或測試程式碼連結至模擬器。

測試擴充功能發出的自訂事件處理常式

如果您實作函式來處理 Firebase Extensions 自訂事件，並使用 Cloud Functions 第 2 版，Cloud Functions 模擬器會與 Eventarc 模擬器搭配，支援 Eventarc 觸發條件。

如要測試會發出事件的擴充功能自訂事件處理常式，您必須安裝 Cloud Functions 和 Eventarc 模擬器。

如果 Eventarc 模擬器正在執行，Cloud Functions 執行階段會將目前程序中的 EVENTARC_EMULATOR 環境變數設為 localhost:9299。設定 EVENTARC_EMULATOR 環境變數後，Firebase Admin SDK 會自動連線至 Eventarc 模擬器。您可以按照「設定 Local Emulator Suite」一節所述，修改預設通訊埠。

正確設定環境變數後，Firebase Admin SDK 會自動將事件傳送至 Eventarc 模擬器。接著，Eventarc 模擬器會回呼 Cloud Functions 模擬器，觸發任何已註冊的處理常式。

您可以在 Emulator Suite UI 中查看函式記錄，瞭解處理常式執行的詳細資料。

設定本機測試環境

如果函式依賴以 dotenv 為基礎的環境設定，您可以在本機測試環境中模擬該行為。

使用本機 Cloud Functions 模擬器時，您可以設定 .env.local 檔案，覆寫專案的環境變數。.env.local 的內容優先順序高於 .env 和專案專屬的 .env 檔案。

舉例來說，專案可能包含以下三個檔案，其中包含開發和本機測試略有不同的值：

.env .env.dev .env.local
PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Local Humans

在本機環境中啟動時，模擬器會載入環境變數，如下所示：

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Cloud Functions 模擬器中的密鑰和憑證

Cloud Functions 模擬器支援使用密鑰儲存及存取機密設定資訊。根據預設，模擬器會嘗試使用應用程式預設憑證存取正式版密鑰。在某些情況下 (例如 CI 環境)，模擬器可能會因權限限制而無法存取 Secret 值。

與 Cloud Functions 模擬器支援環境變數類似，您可以設定 .secret.local 檔案來覆寫 Secret 值。這樣一來，您就能輕鬆在本機測試函式，特別是在無法存取 Secret 值的情況下。

還有哪些工具可用於測試 Cloud Functions？

Cloud Functions 模擬器可搭配其他原型和測試工具使用：

  • Cloud Functions 殼層，可讓您以互動、疊代的方式設計及開發函式原型。殼層採用 Cloud Functions 模擬器，並提供 REPL 樣式的開發介面。不提供與 Cloud Firestore 或 Realtime Database 模擬器的整合。您可以使用殼層模擬資料並執行函式呼叫，模擬與 Local Emulator Suite 目前不支援的產品 (Analytics、遠端設定和 Crashlytics) 互動。
  • Cloud Functions 的 Firebase Test SDK，這是一個採用 Mocha 架構的 Node.js，用於函式開發。實際上，Cloud Functions 測試 SDK 在 Cloud Functions 殼層上提供自動化功能。

如要進一步瞭解 Cloud Functions 殼層和 Cloud Functions 測試 SDK，請參閱「以互動方式測試函式」和「Cloud Functions 的單元測試」。

Cloud Functions 模擬器與正式環境的差異

在大多數用途中，Cloud Functions 模擬器與正式環境相當接近。我們投入大量心力，確保 Node 執行階段中的所有內容都盡可能接近實際工作環境。不過，模擬器不會模擬完整的容器化正式環境，因此雖然函式程式碼會實際執行，但環境的其他方面 (例如本機檔案、函式當機後的行為等) 會有差異。

Cloud IAM

Firebase 模擬器套件不會嘗試複製或遵循任何與 IAM 相關的執行行為。模擬器會遵循提供的 Firebase 安全性規則，但在通常會使用 IAM 的情況下 (例如設定 Cloud Functions 叫用服務帳戶，進而設定權限)，模擬器無法設定，並會使用開發機器上的全域可用帳戶，類似於直接執行本機指令碼。

記憶體和處理器限制

模擬器不會對函式強制執行記憶體或處理器限制。不過，模擬器支援透過 timeoutSeconds 執行階段引數，讓函式逾時。

請注意，在模擬器中執行函式時，函式執行時間可能與正式環境不同。建議您使用模擬器設計及測試函式後，在正式環境中執行有限的測試，確認執行時間。

規劃本機和正式環境的差異

由於模擬器是在本機電腦上執行，因此會依賴本機環境來執行應用程式、內建程式和公用程式。

請注意，Cloud Functions 開發作業的本機環境可能與 Google 正式環境不同：

  • 在本機安裝以模擬正式環境的應用程式 (例如本教學課程中的 ImageMagick)，其行為可能與正式環境不同，尤其是當您需要不同版本或在非 Linux 環境中開發時。建議您在部署函式時，一併部署缺少的程式二進位檔副本。

  • 同樣地，內建公用程式 (例如 ls、mkdir 等殼層指令) 可能與正式版不同，尤其是在非 Linux 環境 (例如 macOS) 中開發時。如要解決這個問題，請使用原生指令的 Node 替代方案，或建構 Linux 二進位檔，與部署作業一併套裝。

重試中

Cloud Functions 模擬器不支援在函式失敗時重試。

後續步驟