Firebase JavaScript SDK 最佳做法

本頁提供提示和疑難排解資訊，協助您解決使用 Firebase JavaScript SDK 時可能遇到的 JavaScript 問題。

遇到其他問題或找不到所需資訊嗎？如要查看更多 Firebase 相關或產品專屬的常見問題，請務必參閱主要 Firebase 常見問題。

您也可以查看 Firebase JavaScript SDK GitHub 存放區，取得最新回報問題和疑難排解清單，並在該處提出自己的問題。

Node.js 建構函式 Admin SDK 與 Firebase JavaScript SDK 不相容

Node.js 的 Firebase Admin SDK 和 Firebase JavaScript SDK 是不同的實作項目，不會共用介面、類別或函式定義。Admin SDK 物件的例項與 Firebase JavaScript SDK 函式不相容。

舉例來說，傳遞至 Firebase JavaScript SDK getDatabase 函式的 Admin SDK FirebaseApp 執行個體會產生下列錯誤：

TypeError: Cannot read properties of undefined (reading 'getProvider')
 at _getProvider
 at getDatabase

整個 Firebase JavaScript SDK API 介面都是如此，不只是 Realtime Database。 反向使用時也是如此。嘗試將 Cloud Firestore JS SDK 的 Timestamp 型別與 Node.js 適用的 Firebase Admin SDK 搭配使用，也會產生類似錯誤。

避免使用衝突的 Firebase JavaScript SDK 版本

如果專案中設定了多個衝突的 Firebase JavaScript SDK 版本做為依附元件，當 SDK 執行個體在 SDK 套件之間傳遞時，就會發生執行階段錯誤。舉例來說，使用 Data Connect 程式庫時，如果 FirebaseApp 的版本不符，就會導致下列錯誤：

Error: Component data-connect has not been registered yet

這個問題通常是因為更新了部分 Firebase SDK 套件的依附元件，但並非全部。如果自動依附元件更新工具變更專案 yarn.lock 或 package-lock.json 檔案中的部分 Firebase SDK 依附元件，就可能發生這種情況。由於許多 Firebase JavaScript SDK 彼此互通，使用不同版本的 SDK 會導致執行階段不相容，

如要修正這個問題，請刪除專案中的 node_modules/ 目錄和 yarn.lock (適用於 yarn) 或 package-lock.json (適用於 npm)，然後重新安裝依附元件。

如果錯誤仍未解決，請使用 npm ls 指令進一步偵錯。這會記錄專案的依附元件，方便您找出 firebase 模組的衝突版本。

舉例來說，下列記錄顯示 package-using-older-firebase 匯入的 Firebase JavaScript SDK 版本有衝突：

$ npm ls firebase --all
your-app@0.0.0
├── firebase@11.2.0
├─┬ @angular/fire@19.0.0
│ ├── firebase@11.2.0 deduped
│ └─┬ rxfire@6.1.0
│   └── firebase@10.14.1 deduped
└─┬ package-using-older-firebase@0.1.0
  └─── firebase@10.14.1

如果應用程式中混用 CJS 和 ESM 的 require 和 import 陳述式，也可能發生錯誤。這會建立多個 Firebase JavaScript SDK 執行個體，彼此互不相同，導致 Firebase JavaScript SDK 無法互通。請增加所選組合工具的詳細程度，以便偵錯這個情境。舉例來說，您可以使用 esbuild analyze 標記來達成這個目的。

確認已將 Service Worker 組合在一起

Service Worker 通常是透過與其餘網頁應用程式不同的管道建構，且不會納入 Webpack 等打包工具的預設設定。

如果您在服務工作站中使用 Firebase JavaScript SDK 的模組化版本，請務必設定應用程式套件組合工具，納入服務工作站來源檔案。以下範例使用 npx，將專案 src 目錄中的 firebase-sw.js 服務工作人員打包：

npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js

如果服務工作人員來源匯入的 ES 模組不支援服務工作人員，或檔案不存在於服務工作人員的範圍內，則未綁定的服務工作人員啟用作業就會失敗。有時這類失敗不會顯示任何訊息，因此很難偵錯。

如要進一步瞭解如何將 Firebase JavaScript SDK 的模組化版本套裝組合到應用程式中，請參閱「搭配 Firebase 使用模組套裝組合工具」。

或者，您也可以從 CDN 匯入 compat Firebase JavaScript SDK 套件，不必進行套件組合：

// Give the service worker access to Firebase Messaging.
// Replace 10.13.2 with the version of the Firebase JS SDK you're using
// in your app.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  ...
});

// Retrieve an instance of Firebase Messaging so that it can handle
// background messages.
const messaging = firebase.messaging();

使用伺服器端轉譯時，請使用 FirebaseServerApp

Firebase JavaScript SDK 原本是為了在瀏覽器環境中執行而設計，伺服器端轉譯 (SSR) 架構的推出，將 SDK 用途推向新的執行階段環境。這些執行階段提供的工具和 API 子集，與網頁瀏覽器提供的相同。

舉例來說，部分 Firebase SDK 需要使用 IndexedDB (僅適用於瀏覽器的 API) 進行資料快取。在某些登入流程中，Firebase Auth 可能需要使用者互動，但無頭伺服器環境無法提供這類互動。App Check 會依據瀏覽器啟發式方法驗證使用者，再建立 App Check 權杖。

在這些新環境中使用 SDK 時，請使用 FirebaseServerApp，這是 FirebaseApp 的新變體，可預先載入 SSR Firebase 執行個體，並載入從用戶端收集的資料。

FirebaseServerApp 支援兩個參數：

  • Auth ID 權杖：如果提供這項權杖，Firebase Auth 會自動登入先前經過驗證的使用者，可能跨越 CSR/SSR 分界的工作階段。
  • App Check 權杖：如果提供權杖，其他 Firebase SDK 就能使用該權杖，不必初始化 App Check 用戶端的執行個體 (瀏覽器環境以外的環境不支援這項操作)。這項功能可為已啟用 App Check 的產品解除 SSR 支援限制，例如 Cloud Functions、Data Connect、Cloud Firestore、Realtime Database 和 Vertex AI。

如需 Next.js 中 FirebaseServerApp 的使用範例，請參閱「使用 FirebaseServerApp 簡化 SSR 應用程式開發作業」。