Firebase JavaScript SDK

<!-- 徽章 -->

<!-- 徽章结束 -->

Firebase JavaScript SDK 实现了使用 Firebase 服务的应用程序所需的客户端库。该 SDK 通过以下方式分发：

• CDN
• npm 包

要开始使用 Firebase，请参阅将 Firebase 添加到您的 JavaScript 项目。

升级到第 9 版

第 9 版具有重新设计的 API，支持树摇优化。阅读升级指南以了解更多信息。

支持的环境

请参阅环境支持。

SDK 开发工作流程

前提条件

Node.js

在开始使用 Firebase JS SDK 之前，您需要在计算机上安装 Node.js。截至 2024 年 4 月 19 日，团队一直在使用 Node.js 版本 20.12.2，但随着我们更新依赖项，所需的 Node.js 版本可能会发生变化。

要下载 Node.js，请访问 https://nodejs.org/en/download/。

注意：您可以使用像 NVM 或 N 这样的工具来安装和管理多个 Node 版本

Yarn

除了 Node.js，我们还使用 yarn 来便于多包开发。

要安装 yarn，请按照其网站上列出的说明进行操作： https://yarnpkg.com/en/docs/install

该仓库当前支持使用 yarn 1.x 构建。例如，安装 yarn 后，运行

$ yarn set version 1.22.11

Java

闭包编译器需要现代 Java 安装。应安装 Java 11+ 版本：https://www.oracle.com/java/technologies/downloads/#java11

验证前提条件

您可以通过在终端中运行以下命令来验证您的设置：

$ node -v
$ yarn -v
$ java -version

您的 node 版本应为 20.12.2，yarn 版本应介于 1.0.0 和 1.22.11 之间，java 版本应为 11.0 或更高。

注意：我们会随着新版本的要求更新文档，但对于 SDK 的持续开发，建议保持这些包的稳定版本

安装依赖项

一旦您在计算机上安装了 Node.js 和 yarn，并验证运行的版本正确无误，您就可以通过在 SDK 根目录运行以下命令来设置开发环境：

$ yarn

安装完所有依赖项后，您可以通过在 SDK 根目录运行以下命令来构建整个 SDK：

$ yarn build

测试 SDK

测试设置

测试 Firebase JS SDK 需要一个生产项目。您可以通过访问 Firebase 控制台 创建一个新项目。

Web 应用设置

访问"项目概览"并在项目名称下选择"添加应用"。使用昵称注册应用并点击完成剩余步骤。如果不执行此步骤，您将在测试设置中遇到以下错误：

FirebaseError: There are no WEB apps associated with this Firebase project

Firestore 数据库设置

访问控制台的"Firestore 数据库"部分并创建一个 Cloud Firestore 数据库。当提示选择初始安全规则集时，选择任意选项（例如"以生产模式启动"），因为这些权限设置将在下面被覆盖。

实时数据库设置

访问控制台的"实时数据库"部分并创建一个实时数据库。当提示选择初始安全规则集时，选择任意选项（例如"以锁定模式启动"），因为这些权限设置将在下面被覆盖。

存储设置

访问控制台的"存储"部分并创建一个存储桶。为了运行测试，您需要更新存储桶的 CORS 规则。

1. 创建一个名为 cors.json 的新文件，内容如下：

[
    {
        "origin": ["http://localhost:8089"],
        "method": ["GET"],
        "maxAgeSeconds": 3600
    }
]

1. 从 https://cloud.google.com/storage/docs/gsutil_install 安装 gsutil
2. 如果这是您第一次使用 gsutil，您需要登录。运行 gcloud auth login 并按照说明登录。
3. 运行 gsutil cors set cors.json gs://<your-cloud-storage-bucket>

更多信息，请访问 https://firebase.google.com/docs/storage/web/download-files#cors_configuration

身份验证支持

访问项目中的身份验证配置，并启用 匿名 登录提供程序以完成项目配置。

自动设置

测试需要配置为使用您在上面"测试设置"部分创建的 Firebase 生产项目。要执行此操作，请运行 yarn test:setup 命令，如下所示：

# 通过基于文本的 UI 选择 Firebase 项目。这将运行 tools/config.js
# 并从 config/ 部署到您的 Firebase 项目。
$ yarn test:setup

# 通过命令行参数指定 Firebase 项目。
$ yarn test:setup --projectId=<test_firebase_project_id>

如果您看到类似以下的错误

HTTP Error: 404, Project '<test_firebase_project_id>' does not exist.

请确保您已按照上面"Firestore 数据库设置"部分的说明创建了数据库。

运行测试

integration 目录中的每个目录以及 packages 目录都有自己的测试套件。在运行测试之前，您需要构建 SDK。可以通过在包的根目录运行以下命令来一起运行所有测试套件：

$ yarn test

此外，您可以通过在单个包目录中运行 yarn test 来单独运行任何测试。

构建 SDK

简介

Firebase JS SDK 由一系列单独的包组成，这些包都包含在这个仓库中。开发通过 yarn workspaces 和 Lerna（一个 monorepo 管理工具）进行协调。

packages 目录中的每个包都构成了我们实现的一部分。SDK 通过这些包的组合构建而成，这些包在 NPM 上以 firebase 作用域 发布。

在本地测试 SDK

在继续进行之前，请确保您的产品包已经构建完成。（如果您之前没有构建过这个仓库，请确保在根目录运行 yarn build） 为了在本地手动测试您的 SDK 更改，您必须使用 yarn link：

$ cd packages/firebase
$ yarn link # 初始化与其他文件夹的链接
$ cd ../<my-product> # 示例：$ cd ../firestore
$ yarn link # 链接您的产品，使其在其他地方可用
$ cd <my-test-app-dir> # cd 到您的个人项目目录
$ yarn link firebase @firebase/<my-product> # 告诉 yarn 使用本地构建的 firebase SDK

这将创建一个符号链接，并将您的 <my-test-app-dir> 指向本地构建的 firebase SDK 版本。

辅助脚本

packages 目录中的每个包都暴露了一个 dev 脚本。这个脚本将为 SDK 的各个部分设置一个观察任务以进行开发。此外，还有一个顶级的 dev 脚本，可以运行来启动所有观察任务以及一个沙盒服务器。

您可以通过在包的根目录运行以下命令来运行 dev 脚本：

$ yarn dev

预推送钩子

作为这个仓库的一部分，我们使用 NPM 包 husky 来实现 git 钩子。我们利用预推送钩子来完成两件事：

• 自动代码样式格式化（使用 prettier）
• 自动 LICENSE 头部插入

贡献

有关为 Firebase JavaScript SDK 做出贡献的更多信息，请参阅 Contributing。

非常感谢

跨浏览器测试平台和开源 <3 由 Sauce Labs 提供