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

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

如果對本頁未涵蓋的主題有疑問，請造訪網路社群。我們也會定期更新這個頁面，加入新主題，歡迎隨時回來查看是否有您想瞭解的主題。

SDK 版本：命名空間和模組化

Firebase 為網頁應用程式提供兩種 API 介面：

  • JavaScript - 命名空間。這是 Firebase 維護多年的 JavaScript 介面，熟悉舊版 Firebase 應用程式的網頁程式開發人員對此並不陌生。由於命名空間 API 不支援持續推出的新功能，因此大多數新應用程式應改用模組化 API。
  • JavaScript - 模組化。這個 SDK 採用模組化方法，可縮減 SDK 大小，並提高 webpack 或 Rollup 等現代 JavaScript 建構工具的效率。

模組化 API 可與建構工具完美整合，建構工具會移除應用程式中未使用的程式碼，這個程序稱為「tree-shaking」。使用這個 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 參考文件。

在應用程式中加入網頁 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) 步驟的必要項目。

搭配使用 npm 和 webpack 或 Rollup 等模組繫結器，可提供最佳化選項，以「tree-shake」方式移除未使用的程式碼，並套用指定的 polyfill，大幅縮減應用程式的大小。實作這些功能可能會增加設定和建構鏈的複雜度，但各種主流 CLI 工具可協助減輕這類問題。這些工具包括 Angular、React、Vue、Next 等。

簡單來說：

  • 提供實用的應用程式大小最佳化功能
  • 您可以使用強大的工具管理模組
  • 使用 Node.js 進行 SSR 時必須提供

CDN (內容傳遞網路)

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

簡單來說：

  • 熟悉且簡單
  • 如果應用程式大小不是主要考量，則適合使用
  • 如果網站未使用建構工具，則適合採用這個方法。

Firebase 網頁 SDK 變化版本

Firebase 的網頁 SDK 可用於瀏覽器和 Node 應用程式。不過，有幾項產品不適用於 Node 環境。請參閱支援的環境清單。

部分產品 SDK 提供獨立的瀏覽器和 Node 變體，每個變體都提供 ESM 和 CJS 格式，有些產品 SDK 甚至提供 Cordova 或 React Native 變體。網頁 SDK 會根據工具設定或環境，提供正確的變體，因此在多數情況下，您不需要手動選取。所有 SDK 變體都旨在協助建構網頁應用程式或用戶端應用程式，供使用者存取，例如在 Node.js 桌面或 IoT 應用程式中。如果您的目標是從特殊權限環境 (例如伺服器) 設定管理員權限，請改用 Firebase Admin SDK。

使用繫結器和框架偵測環境

使用 npm 安裝 Firebase 網頁 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，請務必使用相關聯的設定值 (分別為 measurementId 和 databaseURL)，更新應用程式中使用的 Firebase 設定物件。您隨時可以取得 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，直到整個頁面載入完畢。如果您搭配 <script type="module"> 使用模組化 API CDN 指令碼，這是預設行為。如果您使用命名空間 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 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();

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();

不過，有時您需要同時存取多個 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);

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();

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

如果您正在建構網頁應用程式，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 的程式碼範例。