瞭解網頁版 Firebase

使用 Firebase 開發網頁應用程式時，可能會遇到不熟悉的概念，或需要更多資訊，才能為專案做出正確的決策。本頁面的目標是解答這些問題，或引導您深入探索資源。

如果您對本頁未提及的主題有疑問，請造訪我們其中一個線上社群。 我們也會定期更新這個頁面的內容，因此請定期返回查看我們是否新增了想要瞭解的主題。

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

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

  • JavaScript：命名空間。這是 Firebase 多年維護的 JavaScript 介面，適合擁有舊版 Firebase 應用程式的網頁開發人員熟悉這個介面。由於命名空間 API 無法受益於持續推出的新功能，因此大部分的新應用程式都應改為採用模組化 API。
  • JavaScript - 模組化：這個 SDK 是以模組化方法為基礎，搭配 webpack 或 Rollup 等新型 JavaScript 建構工具，可縮減 SDK 大小並提升效率。

模組化 API 可與建構工具完美整合，方便移除應用程式未使用的程式碼，也就是所謂的「樹動」程序。透過這個 SDK 建構的應用程式能有效縮減大小。雖然命名空間 API 是做為模組使用，但不具嚴格的模組化結構，且無法提供同等大小的縮減程度。

雖然大部分的模組化 API 都採用與命名空間 API 相同的模式，但程式碼的組織方式有所不同。一般來說，命名空間 API 的主要導向命名空間和服務模式，而模組化 API 則著重區分函式。舉例來說，命名空間 API 的點鏈結 (如 firebaseApp.auth()) 會由單一 getAuth() 函式取代，該函式會採用 firebaseApp 並傳回驗證執行個體。

這表示使用命名空間 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 程式庫，包括遠端設定、FCM 等。將 Firebase SDK 新增至網頁應用程式的方式，取決於您搭配應用程式使用的工具 (例如模組組合工具)。

您可以透過其中一種支援方法，將任一可用程式庫新增至應用程式：

  • npm (適用於模組套裝組合)
  • CDN (內容傳遞網路)

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

npm

下載 Firebase npm 套件 (包含瀏覽器和 Node.js 套件) 可取得 Firebase SDK 的本機副本，非瀏覽器應用程式 (例如 Node.js 應用程式、React Native 或 Electron) 可能所需的副本。此下載內容包含 Node.js 和 React Native 套件做為部分套件的選項。如需 SSR 架構的伺服器端轉譯 (SSR) 步驟，就必須使用 Node.js 套裝組合。

將 npm 與模組整合工具 (例如 webpack 或 Rollup) 搭配使用，會提供最佳化選項來「樹動」未使用的程式碼，並套用目標式 polyfill，這可能會大幅減少應用程式的大小占用空間。不過，導入這些功能可能會增加設定和建構鏈的複雜度，但許多主流 CLI 工具可協助您減輕負擔。這些工具包括 Angular、React、Vue、Next 等。

簡單來說：

  • 能針對應用程式大小進行最佳化調整
  • 提供完善的工具管理模組
  • 使用 Node.js 的 SSR 必須提供

CDN (內容傳遞網路)

新增儲存在 Firebase CDN 中的程式庫，是許多開發人員熟悉的簡便 SDK 設定方法。使用 CDN 新增 SDK 時不需要建構工具，您的建構鏈可能比模組封裝工具更簡單、更容易使用。如果您不需要特別注意應用程式的安裝大小，且沒有特殊要求 (例如從 TypeScript 進行轉譯)，建議您選用 CDN。

簡單來說：

  • 熟悉又簡潔
  • 適合未使用應用程式大小的使用者
  • 適合網站未使用建構工具的情況。

Firebase Web SDK 變化版本

Firebase 的 Web SDK 可用於瀏覽器和節點應用程式。不過，在 Node 環境中無法使用幾項產品。請參閱支援的環境清單。

部分產品 SDK 提供不同的瀏覽器和節點變化版本，兩者皆以 ESM 和 CJS 格式提供，而部分產品 SDK 甚至還會提供 Cordova 或 React Native 變化版本。Web SDK 已設定為根據您的工具設定或環境提供正確的變化版本，在多數情況下，您不必手動選取。所有 SDK 變數都是專為建構可供使用者存取的網頁應用程式或用戶端應用程式，例如在 Node.js 電腦或 IoT 應用程式中。如果您的目標是從具有特殊權限的環境 (例如伺服器) 設定管理員權限，請改用 Firebase Admin SDK。

使用組合器和架構進行環境偵測

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

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

瞭解 Firebase 設定物件

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

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

  • 如果您在 Firebase 專案中啟用了 Google Analytics (分析)，設定物件就會包含 measurementId 欄位。如要進一步瞭解這個欄位，請參閱 Analytics (分析) 入門指南。

  • 如果在建立 Firebase 網頁應用程式「之後」啟用 Google Analytics (分析) 或即時資料庫，請務必在應用程式中使用的 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",
  storageBucket: "PROJECT_ID.appspot.com",
  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，方法有兩種：

網頁模組 API

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

網路命名空間 API

// 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 設定資訊。

網頁模組 API

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

網路命名空間 API

// 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 託管，您可能已經完成以下幾個步驟。

如要提供網頁應用程式，請使用 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 的程式碼範例。