详细了解 Web 应用和 Firebase

使用 Firebase 开发 Web 应用时，您可能会遇到一些不熟悉的概念，或者需要更多信息才能针对您的项目做出正确决策。本页面旨在解答这些问题，或者引导您找到包含更多信息的资源。

如果本页面没有涵盖您想要了解的主题，请访问我们的在线社区。 我们还会定期更新此页面，添加新主题，请不时回访，看看我们是否添加了您想要了解的主题。

SDK 版本：命名空间型和模块化

Firebase 为 Web 应用提供了两种 API 接口：

  • JavaScript - 命名空间型。这是 Firebase 多年来一直维护的 JavaScript 接口，有较早期开发的 Firebase 应用的 Web 开发者对它应该很熟悉。由于命名空间型 API 无法从后续的新功能支持中受益，因此大多数新应用都应采用模块化 API。
  • JavaScript - 模块化。此 SDK 基于模块化方法，可通过 webpack 或 Rollup 等现代 JavaScript 构建工具缩减 SDK 大小并提高效率。

模块化 API 可与多种构建工具完美集成，这些工具可以剔除应用中未使用的代码，此过程称为“摇树优化”。利用此 SDK 构建的应用可显著缩减大小。命名空间型 API 虽然可作为模块使用，但并不具备严格意义上的模块化结构，而且大小缩减程度也不及模块化 API。

虽然大部分模块化 API 采用了与命名空间型 API 相同的模式，但代码组织方式并不相同。通常，命名空间型 API 采用命名空间和服务模式，而模块化 API 采用离散函数。例如，命名空间型 API 的句点链在模块化 API 中被单个函数取代，像 firebaseApp.auth() 就被 getAuth() 函数所取代，后者接受一个 firebaseApp 作为参数并返回一个 Authentication 实例。

这意味着使用命名空间型 API 创建的 Web 应用需要重构，才能利用模块化应用设计。如需了解详情，请参阅升级指南。

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 添加到应用的方法

Remote Config、FCM 等大多数 Firebase 产品都有相应的 JavaScript 库。以哪种方式向您的 Web 应用添加 Firebase SDK，取决于要与应用搭配使用的工具（如模块打包器）。

如需将任何可用的库添加到应用中，您可以采用下列支持的方法之一：

  • npm（用于模块打包器）
  • CDN（内容分发网络）

如需了解详细的设置说明，请参阅将 Firebase 添加至您的 JavaScript 应用。您可以查看本部分的其余内容，了解适合您的方案。

npm

下载 Firebase npm 软件包（包括浏览器和 Node.js 软件包）后，您将获得 Firebase SDK 的本地副本，Node.js 应用、React Native 或 Electron 等非浏览器应用可能需要此 SDK。 下载内容包含 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 应用中使用。 但是，有几个产品在 Node 环境中不可用。请参阅支持的环境列表。

某些产品 SDK 提供单独的浏览器和 Node 变体，每种变体都以 ESM 和 CJS 格式提供，还有一些产品 SDK 甚至提供 Cordova 或 React Native 变体。Web SDK 已配置为根据您的工具配置或环境提供正确的变体，在大多数情况下应该不需要手动选择。所有 SDK 变体都旨在帮助构建 Web 应用或客户端应用，以供最终用户在诸如 Node.js 桌面或 IoT 应用中进行访问。如果您的目标是通过特权环境（如服务器）设置管理员权限，请改用 Firebase Admin SDK。

使用打包器和框架进行环境检测

使用 npm 安装 Firebase Web SDK 时，JavaScript 和 Node.js 版本会一并安装。软件包会对环境进行精细的检测，以便为您的应用启用正确的软件包版本。

如果您的代码使用 Node.js require 语句，SDK 会查找适用于 Node.js 的软件包。否则，您必须正确配置打包器的设置，以检测 package.json 文件中的适当入口点字段（例如 main、browser 或 module）。如果您在使用 SDK 时遇到运行时错误，请确保打包器配置为优先选择适合您环境的软件包类型。

了解 Firebase 配置对象

如需在您的应用中初始化 Firebase，您需要提供应用的 Firebase 项目配置。您可以随时获取 Firebase 配置对象。

  • 我们不建议手动修改配置对象，尤其是以下必需的“Firebase 选项”：apiKey、projectId 和 appID。如果您使用这些必需的“Firebase 选项”的无效值或缺失值对您的应用进行初始化，应用的用户可能会遇到严重问题。

  • 如果您在 Firebase 项目中启用了 Google Analytics（分析），则配置对象会包含字段 measurementId。如需详细了解此字段，请参阅 Analytics（分析）使用入门页面。

  • 如果您在创建 Firebase Web 应用之后启用 Google Analytics（分析）或 Realtime Database，请确保您在应用中使用的 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：

Web 模块化 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

Web 命名空间型 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 配置信息。

Web 模块化 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

Web 命名空间型 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

运行本地 Web 服务器以用于开发

如果要构建 Web 应用，您会发现 Firebase JavaScript SDK 的部分组件要求从服务器（而不是从本地文件系统）提供您的 Web 应用。您可以使用 Firebase CLI 运行本地服务器。

如果您为应用设置了 Firebase Hosting，则您可能已完成下方的几个步骤。

如需提供您的 Web 应用，您需要使用命令行工具 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 的示例代码。