管理函式 (第 1 代)

您可以使用 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/ 資料夾中尋找原始碼。您也可以視需要整理程式碼集或多組檔案中的函式。

刪除函式

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

  • 在 Firebase CLI 中使用 functions:delete 明確
  • 明確啟用。Google Cloud 控制台
  • 隱含：在部署前從來源中移除函式。

所有刪除作業都會提示您確認，然後才從正式環境中移除函式。

在 Firebase CLI 中明確刪除函式時，可使用多個引數和函式群組，並指定在特定區域執行的函式。此外，您也可以覆寫確認提示。

  • 刪除所有區域中符合指定名稱的所有函式：

    firebase functions:delete FUNCTION-1_NAME

  • 刪除在非預設區域中執行的指定函式：

    firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

  • 刪除多個函式：

    firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

  • 刪除指定的函式群組：

    firebase functions:delete GROUP_NAME

  • 略過確認提示：

    firebase functions:delete FUNCTION-1_NAME --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

現在有兩個相同的函式正在執行：webhook 在 us-central1 中執行，webhookAsia 在 asia-northeast1 中執行。

接著刪除 webhook：

firebase functions:delete webhook

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

變更函式的觸發條件類型

隨著 Cloud Functions for Firebase 部署作業的發展，您可能會基於各種原因需要變更函式的觸發條件類型。舉例來說，您可能想將某種類型的 Firebase Realtime Database 或 Cloud 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 版本

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

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

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

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

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

  "engines": {"node": "22"}

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

  {
    "functions": {
      "runtime": "nodejs22"
    }
  }

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. 重新部署所有函式。

選擇 Node.js 模組系統

Node.js 的預設模組系統是 CommonJS (CJS)，但目前的 Node.js 版本也支援 ECMAScript 模組 (ESM)。Cloud Functions 兩者都支援。

根據預設，函式會使用 CommonJS。也就是說，匯入和匯出作業會像這樣：

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

exports.helloWorld = functions.https.onRequest(async (req, res) => res.send("Hello from Firebase!"));

如要改用 ESM，請在 package.json 檔案中設定 "type": "module" 欄位：

  {
   ...
   "type": "module",
   ...
  }

設定完成後，請使用 ESM import 和 export 語法：

import functions from "firebase-functions/v1";

export const helloWorld = functions.https.onRequest(async (req, res) => res.send("Hello from Firebase!"));

這兩種模組系統都受到完整支援。您可以選擇最適合專案的方法。詳情請參閱 Node.js 模組說明文件。

控管資源調度行為

根據預設，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) 中設定這些值。

如要在函式原始碼中設定記憶體配置和逾時，請使用 Cloud Functions 2.0.0 版 Firebase SDK 導入的 runWith 參數。這個執行階段選項接受符合 RuntimeOptions 介面的 JSON 物件，該介面定義了 timeoutSeconds 和 memory 的值。舉例來說，這個儲存空間函式會使用 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 — 200MHz
  • 256MB — 400MHz
  • 512MB — 800MHz
  • 1GB — 1.4 GHz
  • 2GB — 2.4 GHz
  • 4GB — 4.8 GHz
  • 8GB — 4.8 GHz

如要在 Google Cloud 控制台設定記憶體配置和逾時，請按照下列步驟操作：

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