將應用程式連線至 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 控制台)。

實際專案會有即時資源，例如資料庫執行個體、儲存空間桶、函式，或您為該 Firebase 專案設定的任何其他資源。

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

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

示範 Firebase 專案沒有實際的 Firebase 設定，也沒有實際資源。這些專案通常是透過程式碼研究室或其他教學課程存取。

示範專案的專案 ID 會加上 demo- 前置字串。

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

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

  • 設定更簡單，因為您可以不必建立 Firebase 專案，即可執行模擬器
  • 安全性更高，因為如果程式碼不小心叫用未模擬的 (實際) 資源，就不會發生資料變更、使用和帳單問題
  • 提供更完善的離線支援功能，因為您不需要連上網際網路即可下載 SDK 設定。

檢測應用程式，讓其與模擬器通訊

檢測可呼叫的函式

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

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 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().useFunctionsEmulator(origin: "http://127.0.0.1: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

為應用程式進行檢測，以模擬工作佇列功能

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

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

為應用程式進行檢測，以模擬背景觸發的函式

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

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

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

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

如果您實作函式來處理 Cloud Functions 第 2 版的 Firebase Extensions 自訂事件，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 中的「Functions」記錄，瞭解處理程序執行作業的詳細資料。

設定本機測試環境

如果函式依賴以 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 Test SDK，這是 Node.js 與 Mocha 架構的組合，可用於函式開發。也就是說，Cloud Functions Test SDK 會在 Cloud Functions 殼層上提供自動化功能。

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

後續步驟