管理功能


您可以使用 Firebase CLI 指令部署、刪除及修改函式,也可以在函式原始碼中設定執行階段選項。

部署函式

如要部署函式,請執行下列 Firebase CLI 指令:

firebase deploy --only functions

根據預設,Firebase CLI 會同時部署來源中的所有函式。如果專案包含超過 5 個函式,建議使用 --only 旗標和特定函式名稱,只部署您編輯過的函式。以這種方式部署特定函式可加快部署程序,並避免超出部署配額。例如:

firebase deploy --only functions:addMessage,functions:makeUppercase

部署大量函式時,您可能會超過標準配額,並收到 HTTP 429 或 500 錯誤訊息。如要解決這個問題,請分組部署函式,每組最多 10 個。

如需可用指令的完整清單,請參閱 Firebase CLI 參考資料

根據預設,Firebase CLI 會在 functions/ 資料夾中尋找原始碼。如要整理程式碼庫或多組檔案中的函式,請參閱這篇文章

清除部署構件

部署函式時,系統會產生容器映像檔並儲存在 Artifact Registry 中。部署的函式不需要這些映像檔即可執行;Cloud Functions會在初始部署時擷取並保留映像檔副本,但函式在執行階段運作時不需要儲存的構件。

雖然這些容器映像檔通常很小,但長期下來可能會累積,進而增加儲存空間費用。如果您打算檢查建構成果或執行容器安全漏洞掃描,可能需要保留這些項目一段時間。

為協助管理儲存空間費用,Firebase CLI 14.0.0 以上版本可讓您為存放部署構件的存放區,設定Artifact Registry清除政策,以便在每次函式部署後清除構件。

您可以使用 functions:artifacts:setpolicy 指令手動設定或編輯清除政策:

firebase functions:artifacts:setpolicy

根據預設,這項指令會將 Artifact Registry 設定為自動刪除超過 1 天的容器映像檔。這樣一來,就能在盡量減少儲存空間費用,以及允許檢查近期建構版本之間取得合理平衡。

您可以使用 --days 選項自訂保留期限:

firebase functions:artifacts:setpolicy --days 7  # Delete images older than 7 days

如果您將函式部署至多個區域,可以使用 --location 選項,為特定位置設定清除政策:

$ firebase functions:artifacts:setpolicy --location europe-west1

選擇停用構件清理作業

如要手動管理圖片清理作業,或不想刪除任何圖片,可以完全停用清理政策:

$ firebase functions:artifacts:setpolicy --none

這項指令會移除 Firebase CLI 建立的所有現有清理政策,並防止 Firebase 在函式部署後設定清理政策。

刪除函式

您可以透過下列方式刪除先前部署的函式:

  • 使用 functions:deleteFirebase CLI 中明確設定
  • 明確Google Cloud 控制台中。
  • 在部署前從來源中移除函式,即可隱含移除函式。

所有刪除作業都會提示您確認,再從正式版中移除函式。

Firebase CLI 中的明確函式刪除作業支援多個引數和函式群組,並可讓您指定在特定區域執行的函式。此外,您也可以覆寫確認提示。

# Delete all functions that match the specified name in all regions.
firebase functions:delete myFunction
# Delete a specified function running in a specific region.
firebase functions:delete myFunction --region us-east-1
# Delete more than one function
firebase functions:delete myFunction myOtherFunction
# Delete a specified functions group.
firebase functions:delete groupA
# Bypass the confirmation prompt.
firebase functions:delete myFunction --force

透過隱含函式刪除功能,firebase deploy 會剖析來源,並從正式版中移除檔案中已移除的函式。

修改函式的名稱、區域或觸發條件

如要重新命名或變更處理正式版流量的函式區域或觸發條件,請按照本節中的步驟操作,以免在修改期間遺失事件。請先確認函式為等冪,再按照下列步驟操作,因為在變更期間,新舊版本的函式會同時執行。

重新命名函式

如要重新命名函式,請在來源中建立函式的新版本 (已重新命名),然後分別執行兩個部署指令。第一個指令會部署新命名的函式,第二個指令則會移除先前部署的版本。舉例來說,如果您有名為 webhook 的 Node.js 函式,想要改為 webhookNew,請按照下列方式修改程式碼:

// before
const functions = require('firebase-functions/v1');

exports.webhook = functions.https.onRequest((req, res) => {
    res.send("Hello");
});

// after
const functions = require('firebase-functions/v1');

exports.webhookNew = functions.https.onRequest((req, res) => {
    res.send("Hello");
});

接著,請執行下列指令來部署新函式:

# Deploy new function called webhookNew
firebase deploy --only functions:webhookNew

# Wait until deployment is done; now both webhookNew and webhook are running

# Delete webhook
firebase functions:delete webhook

變更函式的區域

如果要變更處理正式環境流量的函式指定區域,請依序執行下列步驟,避免遺失事件:

  1. 重新命名函式,並視需要變更其區域。
  2. 部署重新命名的函式,導致兩組區域暫時執行相同的程式碼。
  3. 刪除先前的函式。

舉例來說,假設您有名為 webhook 的函式,目前位於 us-central1 的預設函式區域,而您想將其遷移至 asia-northeast1,則必須先修改原始碼,重新命名函式並修訂區域。

// before
const functions = require('firebase-functions/v1');

exports.webhook = functions
    .https.onRequest((req, res) => {
            res.send("Hello");
    });

// after
const functions = require('firebase-functions/v1');

exports.webhookAsia = functions
    .region('asia-northeast1')
    .https.onRequest((req, res) => {
            res.send("Hello");
    });

然後執行下列指令來部署:

firebase deploy --only functions:webhookAsia

現在有兩個相同的函式正在執行:webhookus-central1 中執行,webhookAsia 則在 asia-northeast1 中執行。

然後刪除 webhook

firebase functions:delete webhook

現在只有一個函式 - webhookAsia,在 asia-northeast1 中執行。

變更函式的觸發類型

隨著時間推移,您可能會基於各種原因,需要變更函式的觸發類型。Cloud Functions for Firebase舉例來說,您可能想將某種 Firebase Realtime DatabaseCloud Firestore 事件改為另一種。

您無法只變更來源程式碼並執行 firebase deploy,藉此變更函式的事件類型。為避免發生錯誤,請按照下列程序變更函式的觸發類型:

  1. 修改原始碼,加入具有所需觸發類型的新函式。
  2. 部署函式,這會導致舊函式和新函式暫時同時執行。
  3. 使用 Firebase CLI 從正式環境明確刪除舊函式。

舉例來說,如果您有名為 objectChanged 的 Node.js 函式,且具有舊版 onChange 事件類型,並想將其變更為 onFinalize,請先重新命名函式,然後編輯函式,使其具有 onFinalize 事件類型。

// before
const functions = require('firebase-functions/v1');

exports.objectChanged = functions.storage.object().onChange((object) => {
    return console.log('File name is: ', object.name);
});

// after
const functions = require('firebase-functions/v1');

exports.objectFinalized = functions.storage.object().onFinalize((object) => {
    return console.log('File name is: ', object.name);
});

然後執行下列指令,先建立新函式,再刪除舊函式:

# Create new function objectFinalized
firebase deploy --only functions:objectFinalized

# Wait until deployment is done; now both objectChanged and objectFinalized are running

# Delete objectChanged
firebase functions:delete objectChanged

設定執行階段選項

Cloud Functions for Firebase 可讓您選取執行階段選項,例如 Node.js 執行階段版本,以及每個函式的逾時、記憶體配置和函式執行個體下限/上限。

根據最佳做法,這些選項 (Node.js 版本除外) 應在函式程式碼內的設定物件中設定。這個 RuntimeOptions 物件是函式執行階段選項的資訊來源,會覆寫透過任何其他方法設定的選項 (例如透過 Google Cloud 控制台或 gcloud CLI 設定的選項)。

如果您的開發工作流程涉及透過 Google Cloud 控制台或 gcloud CLI 手動設定執行階段選項,且您希望在每次部署時覆寫這些值,請將 preserveExternalChanges 選項設為 true。 如果將這個選項設為 true,Firebase 會合併程式碼中設定的執行階段選項,以及目前部署的函式版本設定,並依下列優先順序處理:

  1. 在函式程式碼中設定選項:覆寫外部變更。
  2. 在函式程式碼中,選項設為 RESET_VALUE:以預設值覆寫外部變更。
  3. 函式程式碼中未設定選項,但目前部署的函式已設定選項:使用部署函式中指定的選項。

在大多數情況下,不建議使用 preserveExternalChanges: true 選項,因為您的程式碼將不再是函式執行階段選項的完整事實來源。如果使用,請檢查 Google Cloud 控制台,或使用 gcloud CLI 查看函式的完整設定。

設定 Node.js 版本

Firebase SDK for Cloud Functions 允許選取 Node.js 執行階段。 您可以選擇在專案中,只在與下列其中一個支援的 Node.js 版本對應的執行階段環境中執行所有函式:

  • Node.js 20
  • Node.js 18 (已淘汰)

請參閱支援時間表,瞭解這些 Node.js 版本持續支援的重要資訊。

如要設定 Node.js 版本,請按照下列步驟操作:

您可以在初始化期間於 functions/ 目錄中建立的 package.json 檔案中,設定 engines 欄位的版本。舉例來說,如要只使用第 20 版,請在 package.json 中編輯這行程式碼:

  "engines": {"node": "20"}

如果您使用 Yarn 套件管理工具,或對 engines 欄位有其他特定需求,可以在 firebase.json 中為 Cloud Functions 設定 Firebase SDK 的執行階段:

  {
    "functions": {
      "runtime": "nodejs20"
    }
  }

CLI 會優先使用 firebase.json 中設定的值,而非您在 package.json 中另外設定的任何值或範圍。

升級 Node.js 執行階段

如要升級 Node.js 執行階段:

  1. 確認專案採用 Blaze 定價方案
  2. 確認您使用的是 Firebase CLI 11.18.0 以上版本。
  3. 在初始化期間於 functions/ 目錄中建立的 package.json 檔案中,變更 engines 值。舉例來說,如果您要從版本 16 升級至版本 18,項目應如下所示:"engines": {"node": "18"}
  4. 您也可以選擇使用 Firebase Local Emulator Suite 測試變更。
  5. 重新部署所有函式。

控管資源調度行為

根據預設,Cloud Functions for Firebase 會根據傳入要求數量調整執行個體數量,流量減少時甚至可能縮減至零個執行個體。不過,如果應用程式需要縮短延遲時間,而您希望限制冷啟動次數,則可變更這項預設行為。僅須指定要保持暖機狀態、準備好處理要求的最低容器執行個體數量即可。

同樣地,您也可以設定數量上限,限制執行個體因應傳入要求而進行的資源調度。您可以透過這項設定控管費用,或限制與後端服務 (例如資料庫) 的連線數量。

減少冷啟動次數

如要在原始碼中為函式設定執行個體數量下限,請使用 runWith 方法。這個方法會接受符合 RuntimeOptions 介面的 JSON 物件,該介面會定義 minInstances 的值。舉例來說,這項函式會設定至少 5 個執行個體來保持暖機狀態:

exports.getAutocompleteResponse = functions
    .runWith({
      // Keep 5 instances warm for this latency-critical function
      minInstances: 5,
    })
    .https.onCall((data, context) => {
      // Autocomplete a user's search term
    });

設定 minInstances 的值時,請考量下列事項:

  • 如果 Cloud Functions for Firebase 將應用程式擴展到超出 minInstances 設定,每個超出門檻的執行個體都會冷啟動。
  • 冷啟動對流量尖峰的應用程式影響最大。如果應用程式的流量會突然暴增,且您將 minInstances 值設得夠高,每次流量增加時都能減少冷啟動,延遲時間就會大幅縮短。對於流量穩定的應用程式,冷啟動不太可能嚴重影響效能。
  • 設定最少的執行個體適用於正式環境,但通常應避免在測試環境中設定。如要在測試專案中縮減至零,但仍減少正式環境專案中的冷啟動次數,可以根據 FIREBASE_CONFIG 環境變數設定 minInstances

    // Get Firebase project id from `FIREBASE_CONFIG` environment variable
    const envProjectId = JSON.parse(process.env.FIREBASE_CONFIG).projectId;
    
    exports.renderProfilePage = functions
        .runWith({
          // Keep 5 instances warm for this latency-critical function
          // in production only. Default to 0 for test projects.
          minInstances: envProjectId === "my-production-project" ? 5 : 0,
        })
        .https.onRequest((req, res) => {
          // render some html
        });
    

限制函式的執行個體數量上限

如要在函式原始碼中設定執行個體上限,請使用 runWith 方法。這個方法會接受符合 RuntimeOptions 介面的 JSON 物件,該介面會定義 maxInstances 的值。舉例來說,這個函式會將執行個體數量上限設為 100,以免負荷過重 (假設是舊版資料庫):

exports.mirrorOrdersToLegacyDatabase = functions
    .runWith({
      // Legacy database only supports 100 simultaneous connections
      maxInstances: 100,
    })
    .firestore.document("orders/{orderId}")
    .onWrite((change, context) => {
      // Connect to legacy database
    });

如果 HTTP 函式擴充至 maxInstances限制,系統會將新要求排入佇列 30 秒,如果屆時沒有可用的執行個體,就會以 429 Too Many Requests 回應代碼拒絕要求。

如要進一步瞭解使用最大執行個體設定的最佳做法,請參閱使用 maxInstances 的最佳做法

設定服務帳戶

第 1 代函式的預設服務帳戶 PROJECT_ID@appspot.gserviceaccount.com (名為「App Engine 預設服務帳戶」) 具有廣泛的權限,可讓您與其他 Firebase 和 Google Cloud 服務互動。

您可能想覆寫預設服務帳戶,並將函式限制為僅使用必要的資源。如要執行這項操作,請建立自訂服務帳戶,並使用 .runWith() 方法將該帳戶指派給適當的函式。這個方法會採用含有設定選項的物件,包括 serviceAccount 屬性。

const functions = require("firebase-functions/v1");

exports.helloWorld = functions
    .runWith({
        // This function doesn't access other Firebase project resources, so it uses a limited service account.
        serviceAccount:
            "my-limited-access-sa@", // or prefer the full form: "my-limited-access-sa@my-project.iam.gserviceaccount.com"
    })
    .https.onRequest((request, response) => {
        response.send("Hello from Firebase!");
    });

設定逾時時間和記憶體分配方式

在某些情況下,函式可能需要較長的逾時值或大量記憶體配置。您可以在 Google Cloud 控制台或函式原始碼 (僅限 Firebase) 中設定這些值。

如要在函式原始碼中設定記憶體配置和逾時,請使用 Firebase SDK for Cloud Functions 2.0.0 中導入的 runWith 參數。這個執行階段選項接受符合 RuntimeOptions 介面的 JSON 物件,該介面會定義 timeoutSecondsmemory 的值。舉例來說,這個儲存空間函式會使用 1 GB 的記憶體,並在 300 秒後逾時:

exports.convertLargeFile = functions
    .runWith({
      // Ensure the function has enough memory and time
      // to process large files
      timeoutSeconds: 300,
      memory: "1GB",
    })
    .storage.object()
    .onFinalize((object) => {
      // Do some complicated things that take a lot of memory and time
    });

timeoutSeconds 的最大值為 540,或 9 分鐘。 系統會根據為函式分配的 CPU 量,授予函式相應的記憶體量,詳情請參閱 memory 的有效值清單:

  • 128MB - 200 MHz
  • 256MB - 400 MHz
  • 512MB - 800MHz
  • 1GB - 1.4 GHz
  • 2GB - 2.4 GHz
  • 4GB - 4.8 GHz
  • 8GB - 4.8 GHz

如要在 Google Cloud 控制台中設定記憶體配置和逾時:

  1. 在 Google Google Cloud 控制台中,從左選單選取 Cloud Functions
  2. 在函式清單中點選函式名稱,即可選取函式。
  3. 按一下頂端選單中的「編輯」圖示。
  4. 從標示為「已分配的記憶體」的下拉式選單中,選取記憶體分配量。
  5. 按一下「更多」顯示進階選項,然後在「逾時」文字方塊中輸入秒數。
  6. 按一下「儲存」即可更新函式。