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

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

選擇 Firebase 專案

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

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

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

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

您建立及設定的 Firebase 專案 (很可能透過 Firebase 控制台) 才是實際專案。

實際專案具有即時資源，例如資料庫執行個體、儲存空間值區、函式，或是您為該 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)
MainActivity.kt
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);
MainActivity.java
Swift
Functions.functions().useEmulator(withHost: "localhost", port: 5001)
ViewController.swift

Web

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

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

Web

firebase.functions().useEmulator("127.0.0.1", 5001);
emulator-suite.js

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

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

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

舉例來說，如果使用預設主機通訊埠和區域，簡單的 helloWorld 函式會提供下列服務：

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

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

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

請注意，實際工作環境中使用的調度系統比模擬器中實作的系統更複雜，因此您不應期望模擬行為能精確反映實際工作環境。模擬器中的參數會提供工作調度和重試速率的上限。

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

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

  • Realtime Database 模擬器
  • Cloud Firestore 模擬器
  • Authentication 模擬器
  • Pub/Sub 模擬器
  • Firebase 警告模擬器

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

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

如果您導入函式來處理 Cloud Functions 自訂事件 (使用 Cloud Functions 第 2 版)，Cloud Functions 模擬器會與 Eventarc 模擬器配對，支援 Eventarc 觸發條件。Firebase Extensions

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

如果 Eventarc 模擬器正在執行，Cloud Functions 執行階段會在目前程序中將 EVENTARC_EMULATOR 環境變數設為 localhost:9299。設定 EVENTARC_EMULATOR 環境變數後，Firebase Admin SDKs 會自動連線至 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 環境等特定情況下，模擬器可能會因權限限制而無法存取密鑰值。

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

還有哪些 Cloud Functions 測試工具？

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

  • Cloud Functions Shell，可進行互動式函式原型設計和開發。這個殼層會使用 Cloud Functions 模擬器，並提供 REPL 樣式的介面供開發作業使用。我們不會提供與 Cloud Firestore 或 Realtime Database 模擬器的整合功能。您可以使用殼層模擬資料，並執行函式呼叫，模擬與 Local Emulator Suite 目前不支援的產品互動，包括 Analytics、遠端設定和 Crashlytics。
  • Cloud Functions 專用的 Firebase 測試 SDK，這是搭配 mocha 架構的 Node.js，可供函式開發使用。實際上，Cloud Functions Test SDK 是在 Cloud Functions 殼層上提供自動化功能。

如要進一步瞭解 Cloud Functions Shell 和 Cloud Functions Test 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 模擬器不支援在函式失敗時重試。

後續步驟