設定及管理 App Hosting 後端

App Hosting 易於使用且維護成本低，預設設定已針對大多數用途進行最佳化。同時，App Hosting也提供工具，可讓您根據特定需求管理及設定後端。本指南將說明這些工具和程序。

設定及更新環境變數和密鑰

App Hosting 可讓您使用環境變數處理非機密設定值，並使用 Secret 處理機密參數，例如 API 金鑰、資料庫憑證和服務權杖。

  • 標準環境變數：用於非機密的純文字設定 (例如公開 API 網址、功能旗標或建構目標)。所有專案成員都能查看值。
  • 密鑰：用於機密參數 (例如 OAuth 用戶端密鑰、API 權杖或資料庫密碼)。Secret 由 Cloud Secret Manager 支援。Secret 值受到保護，絕不會在 Firebase 控制台中以純文字顯示。控制台會提供深層連結，方便您直接在 Cloud Secret Manager 中查看及管理 Secret 值。

您可以使用兩種互補的方法定義及管理環境參數：

  • Firebase 控制台：在初始建立後端時，或在後端設定中部署後，快速動態新增、編輯及附加 Secret 或變數。

  • 程式碼優先 (apphosting.yaml)：在存放區的設定檔中宣告環境變數和 Secret 參照，以便進行版本控管部署，或使用 apphosting.<env>.yaml 為不同環境設定不同值。

Firebase 控制台

Firebase 控制台對話方塊的螢幕截圖，用於新增環境變數

apphosting.yaml 

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

在 Firebase 控制台管理變數和密鑰

建立後端時，您可以在 Firebase 控制台設定環境變數和 Secret，也可以隨時在後端設定中進行設定。如果儲存變更時未部署，變更會在下次推出時生效，不會影響目前的推出作業。

在建立後端時設定變數和密鑰

在 Firebase 控制台建立新的 App Hosting 後端時，您可以在設定精靈的「Configure your backend」(設定後端) 步驟中，設定標準環境變數和密鑰：

  1. 在 Firebase 控制台中，依序前往 Hosting & Serverless > App Hosting 然後按一下 Create backend。
  2. 完成初始精靈步驟，選取主要區域和程式碼存放區。
  3. 在「Configure your backend」(設定後端) 部分，找到「Environment variables」(環境變數) 和「Secrets」(密鑰) 的可收合資訊卡，即可新增標準變數及附加密鑰。
  4. 完成後端建立精靈，然後按一下「Finish & deploy」(完成並部署)。

在後端設定中管理變數和密鑰

您可以在後端設定資訊主頁中，查看、新增、編輯或刪除有效後端的環境變數和密鑰：

  1. 在 Firebase 控制台中，選取 App Hosting 後端，然後依序開啟「Settings」(設定) >「Environment」(環境)。
  2. 在「Environment variables」(環境變數) 表格中查看現有設定：
    • 標準變數：值會以純文字形式顯示在可複製的程式碼區塊中。
    • Secret：顯示為可點選的連結，其中包含 Secret 名稱 (點選後會在 Google Cloud 控制台中開啟 Cloud Secret Manager) 和目標版本 (例如 latest 或特定版本號碼，例如 2)。
  3. 如要新增變數或密鑰，請按照下列步驟操作：
    1. 點選「新增」。
    2. 在「步驟 1：選取類型」，選擇「標準環境變數」(適用於所有專案成員可查看的非機密資料) 或「密鑰」(適用於 API 金鑰和存取權受限的機密憑證)，然後點選「下一步」。
    3. 在「Step 2: Configure settings」(步驟 2：進行設定) 中，輸入「Key」(鍵) 名稱和純文字「Value」(值) (適用於標準變數)，或選取「Secret」(密鑰) ID 和「Version」(版本) (適用於密鑰)。
    4. 使用下列任一選項儲存變更：
      • 「Save and deploy」(儲存並部署)：立即更新後端設定，並觸發新的建構作業和推出作業。
      • 「Just save」(僅儲存) (位於「Save and deploy」(儲存並部署) 旁的下拉式箭頭)：儲存設定變更，但不立即推出。更新後的設定會在下次部署時生效。
  4. 如要編輯或刪除現有項目，請按一下資料列結尾的「More actions」(更多動作) (...) 選單：
    • 選取「Edit」(編輯)，修改鍵、值、密鑰對應或版本，然後按一下「Save and deploy」(儲存並部署) 或「Just save」(僅儲存)。
    • 選取「刪除」，並在對話方塊中確認移除。

從 dotenv 個檔案轉移變數

如果是 Next.js 應用程式，含有環境變數的 dotenv 檔案可與 App Hosting 搭配使用。

建立或更新後端時，您可以將環境變數從 dotenv 檔案轉移至 Firebase 控制台，方法是將 dotenv 檔案的完整內容複製並貼到「Settings」(設定) >「Environment」(環境) 中「Add new」(新增) 表單的第一個「Key」(鍵) 欄位。

只要輸入內容採用標準 KEY=value 格式，系統就會自動將以這種方式複製的所有環境變數格式化，您不必逐一輸入：

KEY1=value1
KEY2=value2
KEY3=value3

如要使用任何架構進行複雜或精細的環境變數控制，建議使用 apphosting.yaml。

在 apphosting.yaml 中管理變數和密鑰

如果是程式碼優先工作流程，請在專案存放區 apphosting.yaml 設定檔的 env: 鍵下方，宣告標準環境變數和 Secret 參照 (請參閱「建立及編輯 apphosting.yaml」)。

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

env: 中的每個項目都支援下列欄位：

  • variable：向應用程式 程序公開的環境變數名稱。
  • value：純文字字串值 (適用於標準環境變數)。
  • secret：Cloud Secret Manager 密鑰參照 (適用於密鑰)。您可以使用簡短的密鑰名稱 (例如 myGeminiApiKeySecret 或固定的 myGeminiApiKeySecret@1)，也可以使用完整的資源路徑 (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION)。詳情請參閱「儲存及存取密鑰參數」。
  • availability：控制變數或密鑰是否可在 BUILD 階段、RUNTIME 或兩者中存取。

設定變數可用性

在 Firebase 控制台設定的環境變數和密鑰，在建構和執行階段皆可使用。這也是 apphosting.yaml 中定義項目的預設行為，除非您使用 availability 屬性縮小範圍。在 apphosting.yaml (但不在控制台) 中，您可以將變數或 Secret 限制為僅限建構環境 (BUILD) 或僅限執行階段環境 (RUNTIME)。

在應用程式程式碼中存取變數和密鑰

無論是在 Firebase 控制台或 apphosting.yaml 中設定，環境變數和密鑰都會以標準環境變數的形式 (例如 Node.js 中的 process.env) 公開給應用程式執行階段。

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}
  • 伺服器端存取權：所有環境變數和密鑰，都可在伺服器端執行環境 (例如 Next.js 伺服器元件、API 路徑或 Node.js 後端處理常式) 中安全存取。

  • 用戶端曝光：如要在 Next.js 等架構中向瀏覽器公開標準環境變數，請確保變數索引鍵遵循架構慣例 (例如，前置字元為 NEXT_PUBLIC_)。

    env:
  - variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

變數階層

Firebase App Hosting 會根據來源，依優先順序套用環境變數和密鑰。在 Firebase 控制台中設定的設定一律會覆寫 apphosting.yaml 和 dotenv 檔案中宣告的參數。如果 apphosting.yaml 和 Firebase 控制台中存在同名的環境變數或密鑰，在建構和執行階段執行期間，控制台值會優先採用。

以下是完整的優先順序：

  1. Firebase 控制台 → 在控制台中設定的變數和密鑰
  2. apphosting.<env>.yaml → 在環境專屬 YAML 檔案 (例如 apphosting.staging.yaml) 中指定的變數和密鑰 (請參閱「部署多個環境」)
  3. apphosting.yaml → apphosting.yaml 檔案中指定的變數和密鑰
  4. Firebase 系統：由 Firebase 設定的變數，包含 FIREBASE_CONFIG 或 FIREBASE_WEBAPP_CONFIG 的值，以及設定 SSR 應用程式主機名稱和通訊埠的環境變數 (由 bundle.yaml 中的 App Hosting 轉接器設定)

自動填入的環境變數

App Hosting 會自動填入環境變數。包括由 Google Cloud 填入的變數，以及在設定期間於後端設定 appId 時，Firebase 專屬的環境變數：

  • FIREBASE_CONFIG：(可在建構和執行階段環境中使用) 提供下列 Firebase 專案設定資訊：

    {
  "databaseURL": "https://DATABASE_NAME.firebaseio.com",
  "storageBucket": "PROJECT_ID.firebasestorage.app",
  "projectId": "PROJECT_ID"
}

    當您初始化 Firebase Admin SDK 且不使用引數時，系統會自動套用這項設定。

  • FIREBASE_WEBAPP_CONFIG：(僅適用於建構環境) 提供下列 Firebase 專案設定資訊：

    {
  "apiKey": "API_KEY",
  "appId": "APP_ID",
  "authDomain": "AUTH_DOMAIN.firebaseapp.com",
  "databaseURL": "https://DATABASE_NAME.firebaseio.com",
  "messagingSenderId": "PROJECT_NUMBER",
  "projectId": "PROJECT_ID",
  "storageBucket": "PROJECT_ID.firebasestorage.app"
}</span>

    Firebase JS SDK 會在建構期間，自動檢查 postinstall 指令碼中的 FIREBASE_WEBAPP_CONFIG 環境變數，讓您也能在不使用任何引數的情況下，初始化用戶端 SDK。

如要進一步瞭解如何使用這些環境變數初始化 SDK，請參閱「自動初始化 Firebase Admin SDK 和網頁 SDK」。

請注意，實際 Firebase 設定中的值會對應至您在專案中佈建的特定資源。

變數階層

Firebase App Hosting 會根據變數來源，依優先順序套用變數。舉例來說，在 Firebase 控制台中設定的值一律會覆寫 apphosting.yaml 和 dotenv 檔案中設定的值，或優先於這些值。

以下是完整的優先順序：

  1. Firebase 控制台 → 在控制台中設定的變數
  2. apphosting.<env>.yaml → 在環境專屬 yaml 檔案 (例如 apphosting.staging.yaml) 中指定的變數 (請參閱「部署多個環境」)
  3. apphosting.yaml → apphosting.yaml 檔案中指定的變數
  4. Firebase 系統 → Firebase 設定的變數，包含 firebase_config json 或 firebase_webapp_config 的值，以及設定 SSR 應用程式主機名稱和通訊埠的環境變數 (由 bundle.yaml 中的 App Hosting 轉接器設定)

預留名稱和限制

Cloud Run 容器執行階段合約中定義的環境變數為保留變數，無法設定。

在日後的執行階段版本中，環境提供的環境變數可能會變更 (自動設定的變數除外)。建議的最佳做法是，不要依賴或修改您未明確設定的任何環境變數，並考慮對所有環境變數加上不重複的鍵做為前置字元，避免發生衝突。

部分環境變數鍵僅供內部使用。請勿在設定檔中使用下列任何金鑰：

  • 空字串 ("")
  • 包含「=」的金鑰
  • 開頭為 X_FIREBASE_、X_GOOGLE_ 或 CLOUD_RUN_ 的金鑰
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • 重複的鍵

建立及編輯apphosting.yaml

如要進行進階設定，例如密鑰或並行、CPU 和記憶體限制等執行階段設定，您必須在應用程式的根目錄中建立及編輯 apphosting.yaml 檔案。這個檔案支援參照 Cloud Secret Manager 管理的密鑰，因此可安全地簽入原始碼控管機制。

執行下列指令，建立 apphosting.yaml：

firebase init apphosting

這會建立基本的入門 apphosting.yaml 檔案，其中包含範例 (已註解) 設定。編輯後，一般的 apphosting.yaml 檔案可能如下所示，其中包含後端 Cloud Run 服務的設定、部分環境變數，以及 Cloud Secret Manager 代管密鑰的部分參照：

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

本指南的其餘部分會提供更多資訊和背景，說明這些範例設定。

設定 Cloud Run 服務設定

您可以使用 apphosting.yaml 設定，指定 Cloud Run 服務的佈建方式。Cloud Run 服務的可用設定會顯示在 runConfig 物件中：

  • cpu：每個服務執行個體使用的 CPU 數量 (預設為 1)。
  • memoryMiB：分配給每個服務執行個體的記憶體量，以 MiB 為單位 (預設為 512)。
  • maxInstances：一次可執行的容器數量上限 (預設為 100，由配額管理)。
  • minInstances：一律保持運作的容器數量 (預設為 0)。
  • concurrency：每個服務執行個體可接收的要求數量上限 (預設為 80)。
  • cpuAlwaysAllocated：是否隨時分配 CPU，即使沒有處理要求也一樣 (預設為 false)。

請注意，cpu、memoryMiB 和 concurrency 具有相互依賴的限制 (例如，較高的記憶體設定需要較高的 CPU 限制下限，而部分 CPU 需要 1 的並行)。請參閱 Cloud Run 說明文件，瞭解 CPU 限制和記憶體限制的有效範圍和必要組合。

覆寫建構和執行指令碼

App Hosting 會根據偵測到的架構，推論應用程式的建構和啟動指令。如要使用自訂建構或啟動指令，可以在 apphosting.yaml 中覆寫 App Hosting 的預設值。

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

建構指令覆寫會優先於任何其他建構指令，並讓應用程式停用架構轉接器，以及停用 App Hosting 提供的任何架構專屬最佳化功能。如果轉接程式不支援應用程式功能，最適合使用這個方法。如要變更建構指令，但仍使用提供的轉接器，請改為在 package.json 中設定建構指令碼，如App Hosting架構轉接器所述。

如果您想使用特定指令啟動應用程式，而非 App Hosting 推論的指令，請使用執行指令覆寫功能。

設定建構輸出內容

App Hosting 預設會刪除架構指出的未使用輸出檔案，藉此最佳化應用程式部署作業。如要進一步最佳化應用程式部署大小，或忽略預設最佳化，可以在 apphosting.yaml 中覆寫這項設定。

outputFiles:
  serverApp:
    include: [dist, server.js]

include 參數會接收與應用程式根目錄相關的目錄和檔案清單，這些目錄和檔案是部署應用程式所必需。如要確保所有檔案都保留，請將 include 設為 [.]，系統就會部署所有檔案。

儲存及存取密鑰參數

API 金鑰等機密資訊應儲存為密鑰。您可以在 Firebase 控制台中將密鑰附加至後端，或在 apphosting.yaml 中參照密鑰，避免將機密資訊簽入原始碼控管系統。

secret 類型的參數代表值儲存在 Cloud Secret Manager 中的字串參數。Secret 參數不會直接衍生值，而是會檢查 Cloud Secret Manager 中是否存在該值，並在推出期間載入。

env:
  - variable: API_KEY
    secret: myApiKeySecret

Cloud Secret Manager 中的密鑰可以有多個版本。根據預設，即時後端可用的密鑰參數值，會固定為建構後端時可用的最新密鑰版本。如果您需要管理參數的版本和生命週期，可以在 Firebase 控制台或 apphosting.yaml 中固定特定版本。舉例來說，如要在 apphosting.yaml 中固定至第 5 版，請執行以下操作：

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

您可以使用 Firebase CLI 指令 firebase apphosting:secrets:set 建立密鑰，系統會提示您新增必要權限。這個流程可讓您選擇自動將 Secret 參照新增至 apphosting.yaml。

授予 Cloud Secret Manager 存取權

如要讓 App Hosting 在建構和執行階段推出期間擷取 Secret 值，App Hosting 後端服務帳戶必須具備 Cloud Secret Manager 的存取權限。

如果您是使用 Cloud Secret Manager 控制台或 gcloud CLI 建立 Secret，而非 firebase apphosting:secrets:set，請使用 Firebase CLI 授予後端存取權：

firebase apphosting:secrets:grantaccess SECRET_NAME

或者，您也可以使用 gcloud CLI，將 Secret Manager 密鑰存取者角色 (roles/secretmanager.secretAccessor) 授予 App Hosting 服務代理 (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) 或後端的執行階段服務帳戶：

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

控制台存取權和角色權限

Firebase 控制台會根據使用者 IAM 權限，動態限制環境和 Secret Manager 功能：

  • 檢視者角色：具備唯讀專案權限的使用者可以查看現有設定，但無法變更。
    • 建立後端時，「Create backend」(建立後端) 按鈕會停用。
    • 在後端「Settings」(設定) >「Environment」(環境) 中，「Add new」(新增) 按鈕會停用，且「More actions」(更多動作) (...) 列選單會隱藏。
  • 缺少 Secret Manager 權限：如果使用者沒有與 Cloud Secret Manager 互動的 IAM 權限，會在控制台中看到警告訊息 (請向專案擁有者要求新增 Secret 的權限)：
    • 建立後端時，「Secrets」資訊卡會停用。
    • 在後端「設定」 >「環境」中，點選「新增」時，「Secret」選項會停用，且現有 Secret 項目的「更多動作」 (...) 列選單中會隱藏部分選項。

設定虛擬私有雲存取權

App Hosting 後端可以連線至虛擬私有雲 (VPC) 網路。如需更多資訊和範例，請參閱「將 Firebase App Hosting 連線至虛擬私有雲網路」。

在 apphosting.yaml 檔案中使用 vpcAccess 對應，設定存取權。請使用完整的網路/連接器名稱或 ID。使用 ID 可在測試和正式環境之間，透過不同的連接器/網路進行遷移。

直連虛擬私有雲輸出設定 (apphosting.yaml)：

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

無伺服器連接器設定 (apphosting.yaml)：

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

管理後端

FirebaseApp Hosting 控制台和 Firebase CLI 提供基本管理 App Hosting 後端的指令。本節說明一些較常見的管理工作，包括建立及刪除後端。

建立後端

App Hosting 後端是 App Hosting 建立的代管資源集合，用於建構及執行網頁應用程式。

Firebase 控制台：依序前往 「Hosting & Serverless」 > 「App Hosting」 ，然後按一下「Create backend」(如果這是 Firebase 專案中的第一個後端，請按一下「Get started」)。

Firebase CLI： (13.15.4 以上版本) 如要建立後端，請在本機專案目錄的根目錄執行下列指令，並提供專案 ID 做為引數：

firebase apphosting:backends:create --project PROJECT_ID

無論是使用控制台或 CLI，請按照提示選擇區域、設定 GitHub 連線，並調整下列基本部署設定：

  • 設定應用程式的根目錄 (預設為 /)

    這通常是 package.json 檔案的所在位置。

  • 設定正式分支版本

    這是 GitHub 存放區的分支版本，會部署到線上網址。通常是功能分支或開發分支合併的分支。

  • 接受或拒絕自動推出

    自動推出功能預設為啟用。後端建立完成後，您可以選擇立即將應用程式部署至 App Hosting。

  • 為後端命名。

  • 選取執行階段環境。根據預設，系統會預先選取最新建議的 Node.js 版本。

    • 設定自動更新基本映像檔 (ABIU)。ABIU 預設為啟用，會自動將安全性修補程式套用至基礎環境。如要停用 ABIU，請將執行階段設為「未指定」。

刪除後端

如要完全移除後端，請先使用 Firebase 控制台或 Firebase CLI 刪除後端，然後手動移除相關資產，並特別注意不要刪除其他後端或 Firebase 專案其他部分可能使用的資源。

Firebase 控制台：在「Settings」(設定) 選單中，選取「Delete backend」(刪除後端)。

Firebase CLI： (13.15.4 以上版本)

  1. 執行下列指令，刪除 App Hosting 後端。這會停用後端的所有網域，並刪除相關聯的 Cloud Run 服務：

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (選用) 在 Artifact Registry 的 Google Cloud 控制台分頁中，刪除「firebaseapphosting-images」中的後端映像檔。

  3. 在 Cloud Secret Manager 中，刪除名稱含有「apphosting」的密鑰，請特別注意，確保這些密鑰未用於其他後端或 Firebase 專案的其他部分。