本頁面提供使用 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 函式不相容。
舉例來說，將 Admin SDK 的 FirebaseApp 例項傳遞至 Firebase JavaScript SDK getDatabase 函式，會產生以下錯誤：
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 無法互通。請提高所選 bundler 的詳細程度，以便偵錯此情況。舉例來說，您可以使用 esbuild analyze 標記來達成這個目的。
確認服務工作者已綁定
Service Worker 通常會從與其他網路應用程式分開的管道建構，且不會包含在 Webpack 等套件組合器的預設設定中。
如果您在服務 worker 中使用 Firebase JavaScript SDK 的模組版本，請務必設定應用程式 bundler 以納入服務 worker 來源檔案。以下範例使用 npx 將專案 src 目錄中的 firebase-sw.js 服務 worker 打包：
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 快取資料，而 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 的產品 (例如 Cloud Functions、Data Connect、Cloud Firestore、Realtime Database 和 Vertex AI) 解除 SSR 支援。
如需 Next.js 中 FirebaseServerApp 的使用範例，請參閱「使用 FirebaseServerApp 簡化 SSR 應用程式開發作業」。