將應用程式連線至 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 專案時,您可以為任何或所有支援的產品執行模擬器。

針對您並未模擬的任何產品,應用程式和程式碼將會與即時資源 (資料庫執行個體、儲存空間值區、函式等) 互動。

示範

示範 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)
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().useFunctionsEmulator(origin: "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 將應用程式或測試程式碼連結至模擬器。

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

如果您實作函式來處理 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=人類

AUDIENCE=Dev Humans AUDIENCE=當地人

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

  $ 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 FirestoreRealtime Database 模擬器的整合。您可使用殼層模擬資料並執行函式呼叫,模擬 Local Emulator Suite 目前不支援的產品 (Analytics、遠端設定和 Crashlytics) 互動。
  • Cloud Functions 適用的 Firebase Test SDK,此為含有 mocha 架構的 Node.js,可用於開發函式。也就是說,Cloud Functions Test SDK 會在 Cloud Functions 殼層上提供自動化功能。

如要進一步瞭解 Cloud Functions 殼層和 Cloud Functions 測試 SDK,請參閱互動式測試函式Cloud Functions 的單元測試

Cloud Functions 模擬器與實際環境的差異

在大多數用途上,Cloud Functions 模擬器與正式環境相當接近。我們致力確保節點執行階段中的所有項目都盡可能接近實際工作環境。不過,模擬器不會模擬完整的容器化實際環境,因此雖然函式程式碼會如實執行,但環境的其他部分 (例如本機檔案、函式當機後的行為等) 會有所不同。

Cloud IAM

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

記憶體和處理器限制

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

請注意,如果在模擬器中執行函式,函式執行時間可能會與實際執行時間不同。建議您在使用模擬器設計及測試函式後,在實際工作環境中執行有限的測試,確認執行時間。

規劃本機與實際工作環境的差異

由於模擬器是在本機電腦上執行,因此會因應用程式及內建程式和公用程式而異。

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

  • 在本機安裝來模擬實際工作環境的應用程式 (例如本教學課程的 ImageMagick) 可能會與實際工作環境的行為不同,尤其是您需要在非 Linux 環境中開發不同版本或開發時。建議您同時部署自己遺漏的程式的二進位檔副本,以及函式部署。

  • 同樣地,內建公用程式 (例如 lsmkdir 等殼層指令) 可能與實際工作環境中的版本不同,尤其是在非 Linux 環境 (例如 macOS) 中開發時。如要處理這個問題,您可以使用僅限節點的替代方案取代原生指令,或是建構 Linux 二進位檔與部署作業搭配使用。

重試中

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

後續步驟