瞭解適用於網頁應用程式的 Firebase

使用 Firebase 開發網頁應用程式時，您可能會遇到不熟悉的概念，或是需要更多資訊才能為專案做出正確決策的領域。本頁旨在回答這些問題，或為您提供進一步瞭解的資源。

如果您對本頁未涵蓋的話題有任何疑問，請前往我們的線上社群。我們也會定期更新這個頁面，新增其他主題，歡迎隨時回來查看是否有您想瞭解的主題。

SDK 版本：命名空間和模組

Firebase 為網頁應用程式提供兩種 API 途徑：

  • JavaScript - 命名空間。這是 Firebase 多年來的 JavaScript 介面，也是舊版 Firebase 應用程式的網頁開發人員所熟悉的介面。由於命名空間 API 無法從持續提供的新功能支援中受益，因此大多數新應用程式應改用模組化 API。
  • JavaScript - 模組化。這個 SDK 採用模組化方法，可縮減 SDK 大小，並透過 webpack 或 Rollup 等新式 JavaScript 建構工具提高效率。

模組化 API 可與建構工具完美整合，這些工具會移除應用程式中未使用的程式碼，這個程序稱為「樹狀圖搖動」。使用這個 SDK 建構的應用程式可享有大幅縮減的大小。命名空間 API 雖然可做為模組使用，但沒有嚴格的模組結構，也不會提供相同程度的大小縮減。

雖然大多數模組 API 都遵循與命名空間 API 相同的模式，但程式碼的組織方式不同。一般來說，命名空間 API 會以命名空間和服務模式為導向，而模組 API 則會以個別函式為導向。舉例來說，命名空間 API 的點鏈結 (例如 firebaseApp.auth()) 會在模組化 API 中由單一 getAuth() 函式取代，該函式會接收 firebaseApp 並傳回 Authentication 例項。

也就是說，使用命名空間 API 建立的網頁應用程式需要重構，才能發揮模組化應用程式設計的優勢。詳情請參閱升級指南。

JavaScript：適用於新應用程式的模組化 API

如果您要開始使用 Firebase 進行新整合，則可在新增及初始化 SDK 時選擇採用模組 API。

開發應用程式時，請注意程式碼將主要以函式為主進行排序。在模組化 API 中，服務會做為第一個引數傳遞，然後函式會使用服務的詳細資料執行其餘作業。例如：

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

如需更多範例和詳細資訊，請參閱各產品領域的指南，以及模組化 API 參考說明文件。

在應用程式中新增 Web SDK 的方式

Firebase 為多數 Firebase 產品提供 JavaScript 程式庫，包括 Remote Config、FCM 等。如何在網頁應用程式中新增 Firebase SDK，取決於您在應用程式中使用的工具 (例如模組套件組合器)。

您可以透過下列任一支援的方法，將任何可用程式庫新增至應用程式：

  • npm (適用於模組封包工具)
  • CDN (內容傳遞聯播網)

如需詳細設定操作說明，請參閱「將 Firebase 新增至 JavaScript 應用程式」。本節的其餘部分包含資訊，可協助您從可用的選項中進行選擇。

npm

下載 Firebase npm 套件 (包含瀏覽器和 Node.js 套件) 可取得 Firebase SDK 的本機副本，這可能會用於非瀏覽器應用程式，例如 Node.js 應用程式、React Native 或 Electron。下載內容包含 Node.js 和 React Native 套件，可用於部分套件。Node.js 套件是 SSR 架構伺服器端轉譯 (SSR) 步驟的必要條件。

搭配 webpack 或 Rollup 等模組套件器使用 npm，可提供最佳化選項來「樹狀結構搖動」未使用的程式碼，並套用指定的 polyfill，進而大幅縮減應用程式的大小。實作這些功能可能會使設定和建構鏈變得更複雜，但各種主流的 CLI 工具可協助減輕這項問題。這些工具包括 Angular、React、Vue、Next 等。

簡單來說：

  • 提供有價值的應用程式大小最佳化功能
  • 提供強大的工具來管理模組
  • 使用 Node.js 的 SSR 時，此屬性為必要

CDN (內容傳遞聯播網)

新增儲存在 Firebase CDN 中的程式庫，是許多開發人員熟悉的簡單 SDK 設定方法。使用 CDN 新增 SDK 時，您不需要建構工具，而且與模組套件組合器相比，建構鏈結可能會更簡單，也更容易使用。如果您不太在意應用程式的安裝大小，且沒有特殊需求 (例如從 TypeScript 轉譯)，CDN 可能會是理想的選擇。

簡單來說：

  • 熟悉且簡單
  • 應用程式大小不是主要考量因素時，可使用此選項
  • 如果網站未使用建構工具，則可使用此選項。

Firebase Web SDK 變化版本

Firebase 的網路 SDK 可用於瀏覽器和 Node 應用程式。不過，Node 環境中無法使用部分產品。請參閱支援的環境清單。

部分產品 SDK 會提供獨立的瀏覽器和 Node 變數，每個變數都會以 ESM 和 CJS 格式提供，部分產品 SDK 甚至會提供 Cordova 或 React Native 變數。Web SDK 會根據您的工具設定或環境提供正確的變化版本，在大多數情況下，不需手動選取。所有 SDK 變化版本的設計目的，都是為了協助您建構可供使用者存取的網路應用程式或用戶端應用程式，例如 Node.js 桌面或物聯網應用程式。如果您想在特權環境 (例如伺服器) 中設定管理員存取權，請改用 Firebase Admin SDK。

使用 Bundler 和架構偵測環境

使用 npm 安裝 Firebase Web SDK 時，系統會同時安裝 JavaScript 和 Node.js 版本。這個套件會提供詳細的環境偵測功能，為應用程式啟用正確的套件。

如果程式碼使用 Node.js require 陳述式，SDK 會尋找 Node 專屬套件。否則，您必須正確設定整合工具，才能在 package.json 檔案中偵測正確的進入點欄位 (例如 main、browser 或 module)。如果 SDK 發生執行階段錯誤，請確認整合工具已設定為優先處理環境的正確套件類型。

瞭解 Firebase 設定物件

如要在應用程式中初始化 Firebase，您必須提供應用程式的 Firebase 專案設定。您隨時可以取得 Firebase 設定物件。

  • 我們不建議您手動編輯設定物件，尤其是下列必要的「Firebase 選項」：apiKey、projectId 和 appID。如果您在初始化應用程式時，為這些必要的「Firebase 選項」提供無效值或缺少值，應用程式的使用者可能會遇到嚴重問題。例外狀況是 authDomain，您可以按照使用 signInWithRedirect 的最佳做法更新。

  • 如果您在 Firebase 專案中啟用 Google Analytics，您的設定物件就會包含 measurementId 欄位。如要進一步瞭解這個欄位，請參閱 Analytics 入門頁面。

  • 如果您在建立 Firebase 網頁應用程式後啟用 Google Analytics 或 Realtime Database，請確認您在應用程式中使用的 Firebase 設定物件已更新為相關聯的設定值 (分別為 measurementId 和 databaseURL)。您隨時可以取得 Firebase 設定物件。

以下是已啟用所有服務的設定物件格式 (這些值會自動填入)：

var firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  // The value of `databaseURL` depends on the location of the database
  databaseURL: "https://DATABASE_NAME.firebaseio.com",
  projectId: "PROJECT_ID",
  // The value of `storageBucket` depends on when you provisioned your default bucket (learn more)
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  // For Firebase JavaScript SDK v7.20.0 and later, `measurementId` is an optional field
  measurementId: "G-MEASUREMENT_ID",
};

可用的程式庫

其他設定選項

延遲載入 Firebase SDK (來自 CDN)

您可以延後加入 Firebase SDK，直到整個網頁載入為止。如果您使用模組化 API CDN 指令碼搭配 <script type="module">，則這是預設行為。如果您將命名空間 CDN 指令碼用作模組，請完成下列步驟來延遲載入：

  1. 在每個 Firebase SDK 的 script 標記中新增 defer 標記，然後使用第二個指令碼延後 Firebase 的初始化作業，例如：

    <script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js"></script>

<script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-auth.js"></script>
<script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-firestore.js"></script>

// ...

<script defer src="./init-firebase.js"></script>

  2. 建立 init-firebase.js 檔案，然後在檔案中加入下列內容：

    // TODO: Replace the following with your app's Firebase project configuration
var firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

在單一應用程式中使用多個 Firebase 專案

在大多數情況下，您只需在單一預設應用程式中初始化 Firebase。您可以透過兩種等效方式，從該應用程式存取 Firebase：

Web

import { initializeApp } from "firebase/app";
import { getStorage } from "firebase/storage";
import { getFirestore } from "firebase/firestore";

// Initialize Firebase with a "default" Firebase project
const defaultProject = initializeApp(firebaseConfig);

console.log(defaultProject.name);  // "[DEFAULT]"

// Option 1: Access Firebase services via the defaultProject variable
let defaultStorage = getStorage(defaultProject);
let defaultFirestore = getFirestore(defaultProject);

// Option 2: Access Firebase services using shorthand notation
defaultStorage = getStorage();
defaultFirestore = getFirestore();
app_default_init_options.js

Web

// Initialize Firebase with a "default" Firebase project
const defaultProject = firebase.initializeApp(firebaseConfig);

console.log(defaultProject.name);  // "[DEFAULT]"

// Option 1: Access Firebase services via the defaultProject variable
let defaultStorage = defaultProject.storage();
let defaultFirestore = defaultProject.firestore();

// Option 2: Access Firebase services using shorthand notation
defaultStorage = firebase.storage();
defaultFirestore = firebase.firestore();
firebaseapp.js

不過，有時您可能需要同時存取多個 Firebase 專案。舉例來說，您可能想從某個 Firebase 專案的資料庫讀取資料，但將檔案儲存在其他 Firebase 專案中。或者，您可能想驗證一個專案，同時讓另一個專案保持未驗證狀態。

Firebase JavaScript SDK 可讓您在單一應用程式中同時初始化及使用多個 Firebase 專案，每個專案都會使用自己的 Firebase 設定資訊。

Web

import { initializeApp, getApp } from "firebase/app";
import { getStorage } from "firebase/storage";
import { getFirestore } from "firebase/firestore";

// Initialize Firebase with a default Firebase project
initializeApp(firebaseConfig);

// Initialize Firebase with a second Firebase project
const otherProject = initializeApp(otherProjectFirebaseConfig, "other");

console.log(getApp().name);  // "[DEFAULT]"
console.log(otherProject.name);    // "otherProject"

// Use the shorthand notation to access the default project's Firebase services
const defaultStorage = getStorage();
const defaultFirestore = getFirestore();

// Use the otherProject variable to access the second project's Firebase services
const otherStorage = getStorage(otherProject);
const otherFirestore = getFirestore(otherProject);
app_multi_project_init_options.js

Web

// Initialize Firebase with a default Firebase project
firebase.initializeApp(firebaseConfig);

// Initialize Firebase with a second Firebase project
const otherProject = firebase.initializeApp(otherProjectFirebaseConfig, "other");

console.log(firebase.app().name);  // "[DEFAULT]"
console.log(otherProject.name);    // "otherProject"

// Use the shorthand notation to access the default project's Firebase services
const defaultStorage = firebase.storage();
const defaultFirestore = firebase.firestore();

// Use the otherProject variable to access the second project's Firebase services
const otherStorage = otherProject.storage();
const otherFirestore = otherProject.firestore();
firebaseapp.js

執行本機網路伺服器進行開發

如果您要建構網頁應用程式，Firebase JavaScript SDK 的部分內容要求您從伺服器 (而非本機檔案系統) 提供網頁應用程式。您可以使用 Firebase CLI 執行本機伺服器。

如果您已為應用程式設定 Firebase Hosting，可能已完成下列幾個步驟。

如要提供網頁應用程式，您將使用 Firebase CLI 指令列工具。

  1. 請參閱 Firebase CLI 說明文件，瞭解如何安裝 CLI 或更新至最新版本。

  2. 啟動 Firebase 專案。在本機應用程式目錄的根目錄中執行下列指令：

    firebase init

  3. 啟動本機伺服器進行開發。在本機應用程式目錄的根目錄中執行下列指令：

    firebase serve

Firebase JavaScript SDK 的開放原始碼資源

Firebase 支援開放原始碼開發作業，並鼓勵社群提供貢獻和意見回饋。

Firebase JavaScript SDK

大部分的 Firebase JavaScript SDK 都是以開放原始碼程式庫的形式，在我們的公開 Firebase GitHub 存放區中開發。

快速入門範例

Firebase 會維護網頁上大多數 Firebase API 的快速入門範例集合。您可以在我們的公開 Firebase GitHub 快速入門存放區中找到這些快速入門範例。您可以將這些快速入門課程當成使用 Firebase SDK 的程式碼範例。