升级到模块化 Web SDK (v9)

对于目前正在使用 Web SDK 8 或更低版本的应用,应考虑按照本指南中的说明迁移到版本 9。

本指南假定您熟悉 v8,并且将利用模块打包器(例如 webpackRollup)进行升级并持续进行 v9 的开发。

强烈建议在开发环境中使用模块打包器。如果您不使用模块打包器,则无法利用 v9 在缩减应用大小方面的主要优势。您需要使用 npmyarn 来安装 SDK。

兼容型库简介

Web SDK 版本 9 提供两种类型的库:

  • 模块化 - 一种新的 API 接口,用于实现摇树优化(移除未使用的代码),使您的 Web 应用尽可能精简快速。
  • 兼容型 - 一种熟悉的 API 接口,与版本 8 完全兼容,让您无需一次性更改所有 SDK 代码,即可升级到版本 9。与 v8 对应的库相比,兼容型库在大小或性能方面的优势很少,甚至没有优势。

本指南假定您将利用 v9 兼容型库来推动升级。这些库让您可以一边继续使用 v8 的代码,一边逐步针对 v9 重构代码。这意味着,您在升级过程中可以更轻松地编译和调试应用。

对于极少使用 Web SDK 的应用,在不使用 v9 兼容型库的情况下重构 v8 代码或许是切实可行的。如果要升级此类应用,您可以按照本指南中有关“v9 模块化库”的说明进行操作,而无需使用兼容型库。

升级流程简介

升级流程的每个步骤都限定了范围,这样您便可以完成应用源代码的修改,然后在不出现中断的情况下编译并运行源代码。总的来说,如需升级应用,您需要执行以下操作:

  1. 将 v9 库和兼容型库添加到您的应用中。
  2. 将代码中的 import 语句更新为使用 v9 兼容型库。
  3. 将代码重构为模块化样式。
  4. 移除了用于身份验证的 Authentication compat 库和 compat 代码,以实现应用大小优势。
  5. 将初始化代码更新为模块化样式。
  6. 移除应用中所有剩余的 v9 兼容型语句和代码。

获取 v9 SDK

如需开始使用,请使用 npm 获取 v9 库和兼容型库(最新版本 https://www.npmjs.com/package/firebase):

npm i firebase@10.12.1

# OR

yarn add firebase@10.12.1

将导入项更新为 v9 兼容型库

在将依赖项从 v8 更新为 v9 后,为了确保代码正常运行,请将 import 语句更改为使用每次导入的“compat”版本。例如:

之前:v8

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

之后:v9 兼容型库

// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

重构为模块化样式

v8 对应的 API 基于点链命名空间和服务模式,而 v9 模块化方法意味着您的代码将主要围绕函数进行组织。在版本 9 中,firebase/app 软件包和其他软件包不会返回包含软件包中所有方法的全面导出结果,而是会导出个别函数。

在 v9 中,服务作为第一个参数传递,函数随后会使用服务的详细信息执行其余操作。

示例:重构一个简单的 Authentication 函数

之前:v9 兼容型库

v9 兼容型库的代码与 v8 的代码完全相同,但导入方面发生了变化。在升级过程中使用兼容型库后,您可以一边继续使用 v8 代码,一边逐步针对 v9 重构代码。

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => {
  // Check for user status
});

之后:v9 模块化库

getAuth 函数将 firebaseApp 作为其第一个参数。onAuthStateChanged 函数不会像在版本 8 中那样与身份验证实例进行链接;而是会成为一个自由函数,将 auth 作为其第一个参数。

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

更新初始化代码

更新应用的初始化代码,使用新的模块化 v9 语法。重构应用中的所有代码后,请务必更新初始化代码;这是因为 firebase.initializeApp() 会初始化兼容型和模块化 API 的全局状态,而模块化 initializeApp() 函数仅会初始化模块化 API 的状态。

之前:v9 兼容型库

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

之后:v9 模块化库

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

移除兼容型代码

为了使用 v9 模块化 SDK 精简应用大小,您最终应将所有调用转换为上述的模块化样式,并从代码中移除所有 import "firebase/compat/* 语句。完成后,代码中不应再包含对 firebase.* 全局命名空间的引用或版本 8 SDK 样式中任何其他代码的引用。

版本 9 的好处和限制

与早期版本相比,完全模块化的 v9 具有以下优势:

  • v9 可大幅缩减应用大小。它采用新型的 JavaScript 模块格式,允许执行“摇树(优化)优化”做法,这样,您只需导入应用需要的工件。与使用 v8 构建的类似应用相比,使用 v9 进行摇树优化可使大小(以 Kb 为单位)减少 80%,具体取决于您的应用。
  • 版本 9 将继续受益于后续的功能开发,而版本 8 将在未来的某个时间冻结。