本页针对在使用 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 标志来实现此目的。
确保服务 worker 已捆绑
服务工件通常通过与 Web 应用其余部分不同的流水线构建，并且不会包含在 Webpack 等捆绑工具的默认配置中。
如果您在服务工作器中使用 Firebase JavaScript SDK 的模块化版本，请务必将应用捆绑工具配置为包含服务工作器源文件。以下示例使用 npx 将 firebase-sw.js 服务工作器捆绑到项目的 src 目录中：
npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js
如果未打包的 Service Worker 引用不支持 Service Worker 的 ES 模块或 Service Worker 作用域中不存在的文件，则其激活将会失败。有时，这些失败会静默发生，并且很难调试。
如需详细了解如何将 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 使用进入新的运行时环境。这些运行时提供 Web 浏览器提供的部分工具和 API。
例如，某些 Firebase SDK 需要使用 IndexedDB（一种仅限浏览器的 API）进行数据缓存。Firebase Authentication 在某些登录流程中可能需要用户互动，而这在无头服务器环境中是不可能的。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 应用开发。