您可以為不同的原型和測試環境安裝及設定 Firebase 本機模擬器套件,無論是一次性原型工作階段還是實際運作規模的持續整合工作流程都不例外。
安裝本機模擬器套件
安裝模擬器套件前,您會需要:
如何安裝模擬器套件:
- 安裝 Firebase CLI。如果您尚未安裝 Firebase CLI,請立即安裝。
您需要 CLI 8.14.0 以上版本才能使用模擬器套件。如要查看安裝的版本,請使用下列指令:
firebase --version
- 如果尚未將目前的工作目錄初始化為 Firebase 專案,請按照畫面上提示操作,指定要使用的產品:
firebase init
- 設定模擬器套件。這個指令會啟動設定精靈,方便您選取需要的模擬器、下載對應的模擬器二進位檔檔案,以及設定模擬器通訊埠 (如果不適用預設值)。
firebase init emulators
安裝模擬器後,系統不會執行更新檢查,除非您更新 Firebase CLI 版本,否則不會進行其他自動下載作業。
設定模擬器套件
您可以視需要在 firebase.json
檔案中設定模擬器的網路通訊埠和安全性規則定義的路徑:
- 執行
firebase init emulators
或透過手動編輯firebase.json
來變更模擬器通訊埠。 - 手動編輯
firebase.json
,即可變更安全性規則定義的路徑。
如果您未設定這些設定,模擬器會監聽其預設通訊埠,且 Cloud Firestore、即時資料庫和 Cloud Storage for Firebase 模擬器會以開放資料安全性的方式執行。
指令 | 說明 |
---|---|
啟動模擬器 | 啟動模擬器初始化精靈。找出要安裝的模擬器,並視需要指定模擬器通訊埠設定。init emulators 不會破壞性;接受預設值會保留目前的模擬器設定。 |
通訊埠設定
每個模擬器都會以偏好的預設值繫結至電腦上的不同通訊埠。
模擬器 | 預設通訊埠 |
---|---|
驗證機制 | 9099 |
模擬器套件 UI | 4000 |
Cloud Functions | 5001 |
Eventarc | 9299 |
即時資料庫 | 9000 |
Cloud Firestore | 8080 |
Cloud Storage for Firebase | 9199 |
Firebase 託管 | 5000 |
Pub/Sub | 8085 |
專案 ID 設定
視您叫用模擬器的方式而定,您可以使用不同的 Firebase 專案 ID,或針對特定專案 ID 執行多個模擬器執行個體,執行模擬器的多個執行個體。在這類情況下,模擬器執行個體會在獨立環境中執行。
一般來說,建議您為所有模擬器叫用設定一個專案 ID,讓模擬器套件 UI、不同的產品模擬器,以及特定模擬器執行的所有執行個體都能在所有情況下正確通訊。
本機模擬器套件在環境中偵測到多個專案 ID 時會發出警告,不過您可以在 firebase.json
中將 singleProjectMode
金鑰設為 false
,以覆寫這個行為。
您可以檢查專案 ID 宣告是否在下列位置不一致:
- 指令列中的預設專案。根據預設,系統會在啟動時從透過
firebase init
或firebase use
選取的專案中取得專案 ID。如要查看專案清單 (並瞭解已選取哪個專案),請使用firebase projects:list
。 - 規則單元測試。通常在呼叫規則單元測試程式庫方法
initializeTestEnvironment
或initializeTestApp
時,會指定專案 ID。 - 指令列
--project
旗標。傳遞 Firebase CLI--project
旗標會覆寫預設專案。您必須確保標記值與單元測試和應用程式初始化中的專案 ID 相符。
此外,也請檢查您在設定 Apple 平台、Android 和網路專案時所做的平台專屬專案 ID 設定。
安全性規則設定
模擬器會從 firebase.json
中的 database
、firestore
和 storage
設定金鑰取得安全性規則設定。
{
// Existing firebase configuration ...
"database": {
"rules": "database.rules.json"
},
"firestore": {
"rules": "firestore.rules"
},
"storage": {
"rules": "storage.rules"
}
// ...
// Optional emulator configuration. Default
// values are used if absent.
"emulators": {
"singleProjectMode": false, // do not warn on detection of multiple project IDs
"firestore": {
"port": "8080"
},
"ui": {
"enabled": true, // Default is `true`
"port": 4000 // If unspecified, see CLI log for selected port
},
"auth": {
"port": "9099"
},
"pubsub": {
"port": "8085"
}
}
}
指定 Java 選項
即時資料庫模擬器、Cloud Firestore 模擬器,以及部分 Cloud Storage for Firebase 模擬器均以 Java 為基礎,可透過環境變數 JAVA_TOOL_OPTIONS
使用 JVM 旗標進行自訂。
例如,如果遇到 Java 堆積空間相關錯誤,您可以將 Java 堆積大小上限提高至 4 GB:
export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start
您可以指定多個標記,並以半形空格分隔,例如 JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g"
。這些標記只會影響模擬器的 Java 元件,不會影響 Firebase CLI 的其他部分,例如 Emulator Suite UI。
啟動模擬器
您可以啟動模擬器持續執行,直到手動終止,或執行指定測試指令碼的期間,再自動關閉。
指令 | 說明 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
emulators:start | 針對 firebase.json 中設定的 Firebase 產品啟動模擬器。模擬器程序會繼續執行,直到明確停止為止。呼叫 emulators:start 會將模擬器下載到 ~/.cache/firebase/emulators/ (如果尚未安裝)。
|
||||||||||||
emulators:exec scriptpath | 針對 firebase.json 中設定的 Firebase 產品啟動模擬器,然後前往 scriptpath 執行指令碼。指令碼執行完畢後,模擬器程序就會自動停止。
|
firebase emulators:exec
方法通常更適合用於持續整合工作流程。
匯出及匯入模擬器資料
您可以從驗證、Cloud Firestore、即時資料庫和 Cloud Storage for Firebase 模擬器中匯出資料,做為可共用的通用基準資料集。如上所述,您可以使用 --import
標記匯入這些資料集。
emulators:export export_directory |
驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器。從執行中的 Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器執行個體匯出資料。如果指定的
您可以使用上述的 |
與持續整合系統整合
執行容器化模擬器套件映像檔
在一般 CI 設定中,以容器安裝及設定模擬器套件相當簡單。
請注意以下幾個問題:
JAR 檔案是在
~/.cache/firebase/emulators/
安裝及快取。- 建議您將這個路徑新增至持續整合快取設定,以免重複下載。
如果存放區中沒有
firebase.json
檔案,您必須在emulators:start
或emulators:exec
指令中新增指令列引數,以指定要啟動哪一個模擬器。例如:--only functions,firestore
。
產生驗證權杖 (僅限代管模擬器)
如果您的持續整合工作流程依賴於 Firebase 託管,您需要使用權杖登入,才能執行 firebase emulators:exec
。其他模擬器則不需要登入。
如要產生權杖,請在本機環境執行 firebase login:ci
,這不應從持續整合系統執行。按照操作說明進行驗證。由於每個版本都有效,因此每個專案只需執行這個步驟一次。憑證應視為密碼;請務必妥善保管。
如果 CI 環境允許您指定可在建構指令碼中使用的環境變數,只要建立名為 FIREBASE_TOKEN
的環境變數,且值是存取權杖字串即可。Firebase CLI 會自動選取 FIREBASE_TOKEN
環境變數,接著模擬器會正確啟動。
萬不得已時,您可以直接在建構指令碼中加入權杖,但請確保不受信任的方無法存取。針對這個硬式編碼方法,您可以將 --token "YOUR_TOKEN_STRING_HERE"
新增至 firebase emulators:exec
指令。
使用 Emulator Hub REST API
列出執行中的模擬器
如要列出目前執行中的模擬器,請傳送 GET
要求至 Emulator Hub 的 /emulators
端點。
curl localhost:4400/emulators
結果會是 JSON 物件,列出所有執行中的模擬器及其主機/通訊埠設定,例如:
{
"hub":{
"name": "hub",
"host": "localhost",
"port": 4400
},
"functions": {
"name": "functions",
"host": "localhost",
"port": 5001
}
"firestore": {
"name": "firestore",
"host": "localhost",
"port": 8080
}
}
啟用 / 停用背景函式觸發條件
在某些情況下,您必須暫時停用本機函式和擴充功能觸發條件。例如,您可以刪除 Cloud Firestore 模擬器中的所有資料,但不要觸發正在 Cloud Functions 或擴充功能模擬器中執行的任何 onDelete
函式。
如要暫時停用本機函式觸發條件,請傳送 PUT
要求至 Emulator Hub 的 /functions/disableBackgroundTriggers
端點。
curl -X PUT localhost:4400/functions/disableBackgroundTriggers
結果會是列有目前狀態的 JSON 物件。
{
"enabled": false
}
如要在停用本機函式觸發條件後啟用,請傳送 PUT
要求至 Emulator Hub 的 /functions/enableBackgroundTriggers
端點。
curl -X PUT localhost:4400/functions/enableBackgroundTriggers
結果會是列有目前狀態的 JSON 物件。
{
"enabled": true
}
模擬器 SDK 整合
本節中的表格會指出用戶端和 Admin SDK 支援的模擬器。Future 表示目前已規劃模擬器支援,但尚未提供。
用戶端 SDK 可用性
Android | Apple 平台 | 網頁 |
Firebase UI Android |
Firebase UI iOS |
Firebase UI 網頁版 |
|
---|---|---|---|---|---|---|
即時資料庫 | 19.4.0 版 | 7.2.0 | 8.0.0 版 | 6.4.0 版 | 後續 | 不適用 |
Cloud Firestore | 21.6.0 版 | 7.2.0 | 8.0.0 版 | 6.4.0 版 | 後續 | 不適用 |
驗證機制 | 20.0.0 版 | 7.0.0 版 | 8.0.0 版 | 7.0.0 版 | 後續 | 4.7.2 版 |
Cloud Storage for Firebase | 20.0.0 版 | 8.0.0 版 | 8.4.0 版 | 7.0.0 版 | 11.0.0 版 | 不適用 |
Cloud Functions | 19.1.0 版 | 7.2.0 | 8.0.0 版 | 不適用 | 不適用 | 不適用 |
託管 | 不適用 | 不適用 | 不適用 | 不適用 | 不適用 | 不適用 |
擴充功能 | 不適用 | 不適用 | 不適用 | 不適用 | 不適用 | 不適用 |
Admin SDK 可用性
節點 | Java | Python | Go | |
---|---|---|---|---|
即時資料庫 | 8.6.0 版 | 6.10.0 版 | 2.18.0 版 | 後續 |
Cloud Firestore | 8.0.0 版 | 6.10.0 版 | 3.0.0 | 1.0.0 |
驗證機制 | 9.3.0 版 | 7.2.0 | 5.0.0 | 4.2.0 版 |
Cloud Storage for Firebase | 9.8.0 版 | 後續 | 後續 | 後續 |
Cloud Functions | 不適用 | 不適用 | 不適用 | 不適用 |
託管 | 不適用 | 不適用 | 不適用 | 不適用 |
擴充功能 | 不適用 | 不適用 | 不適用 | 不適用 |