Firebase CLI 参考文档

Firebase CLI (GitHub) 提供了各种用于管理、查看 Firebase 项目并在其中进行部署的工具。

在使用 Firebase CLI 之前，请设置 Firebase 项目。

设置或更新 CLI

安装 Firebase CLI

您可以使用与您的操作系统、经验水平和/或使用场景相匹配的方法来安装 Firebase CLI。无论采用何种方式安装 CLI，您都可以使用相同的功能和 firebase 命令。

Windows macOS Linux

Windows

您可以使用以下任何一种方法来安装 Windows 版 Firebase CLI：

macOS 或 Linux

您可以使用以下任一种方法安装 macOS 版或 Linux 版 Firebase CLI：

登录并测试 Firebase CLI

安装 CLI 后，您必须通过身份验证。随后可以通过列出 Firebase 项目来确认身份验证。

1. 运行以下命令，使用您的 Google 账号登录 Firebase：

   firebase login

   此命令会将您的本地机器与 Firebase 关联，并授予您对 Firebase 项目的访问权限。

2. 通过列出 Firebase 项目来测试 CLI 是否已正确安装，以及是否能访问您的账号：运行以下命令：

   firebase projects:list

   显示的列表应与 Firebase 控制台中列出的 Firebase 项目相同。

更新到最新的 CLI 版本

一般来说，您应该使用最新的 Firebase CLI 版本。

更新 CLI 版本的方式取决于您的操作系统以及 CLI 的安装方式。

将 CLI 与 CI 系统配合使用

Firebase CLI 需要使用浏览器来完成身份验证，不过该 CLI 与 CI 和其他无头环境完全兼容。

1. 在装有浏览器的机器上安装 Firebase CLI。

2. 通过运行以下命令来启动登录流程：

   firebase login:ci

3. 访问提供的网址，然后使用 Google 账号登录。

4. 输出一个新的刷新令牌。当前的 CLI 会话不会受到影响。

5. 将输出的令牌以安全但可访问的方式存储在 CI 系统中。

6. 在运行 firebase 命令时使用此令牌。您可以使用以下两种方法中的任一种：

   • 方法 1：将令牌存储为环境变量 FIREBASE_TOKEN。您的系统会自动使用令牌。

   • 方法 2：在 CI 系统中运行所有 firebase 命令时均使用 --token TOKEN 标志。
     令牌加载的优先顺序为标志、环境变量、所需的 Firebase 项目。

初始化 Firebase 项目

使用 CLI 执行的许多常见任务（如部署到 Firebase 项目）都需要用到项目目录。您可以使用 firebase init 命令创建项目目录。项目目录通常就是源代码控制根目录，在运行 firebase init 之后，该目录会包含一个 firebase.json 配置文件。

如需初始化新的 Firebase 项目，请在应用目录下运行以下命令：

firebase init

firebase init 命令会引导您逐步设置项目目录和某些 Firebase 产品。在项目初始化期间，Firebase CLI 会要求您完成以下任务：

• 选择要在 Firebase 项目中设置的 Firebase 产品。

  此步骤提示您为所选产品的特定文件设置配置。如需详细了解这些配置，请参阅具体产品（例如 Hosting）的文档。请注意，您以后可以随时运行 firebase init 来设置更多 Firebase 产品。

• 选择默认的 Firebase 项目。

  此步骤会将当前项目目录与一个 Firebase 项目相关联，以便项目专用命令（如 firebase deploy）会针对相应的 Firebase 项目运行。

  您还可以将同一个项目目录与多个 Firebase 项目关联（如预演项目和生产项目）。

在初始化结束时，Firebase 会在本地应用目录的根目录下自动创建以下两个文件：

• firebase.json 配置文件，其中列出了您的项目配置。

• .firebaserc 文件，其中存储有您的项目别名。

firebase.json 文件

运行 firebase init 命令会在您的项目目录的根目录下创建一个 firebase.json 配置文件。

您需要创建 firebase.json 文件才能使用 Firebase CLI 部署资源，因为该文件指定将项目目录中的哪些文件和设置部署到您的 Firebase 项目。由于某些设置既可以在项目目录中定义，也可以在 Firebase 控制台中定义，因此请确保解决任何潜在的部署冲突。

您可以直接在 firebase.json 文件中配置大多数 Firebase Hosting 选项。但是，对于其他可以使用 Firebase CLI 部署的 Firebase 服务，firebase init 命令会创建特定文件（例如，用于 Cloud Functions 的 index.js 文件），您可以在其中为这些服务定义相关设置。您还可以在 firebase.json 文件中设置部署前钩子或部署后钩子。

下面是包含默认设置的示例 firebase.json 文件（假定您在初始化期间选择 Firebase Hosting、Cloud Firestore 和 Cloud Functions for Firebase，并且选择了 TypeScript 源代码和 lint 选项）。

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  },
  "firestore": {
      "rules": "firestore.rules",
      "indexes": "firestore.indexes.json"
  },
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint",
      "npm --prefix \"$RESOURCE_DIR\" run build"
    ]
  }
}

默认情况下使用 firebase.json，但您可以传递 --config PATH 标志以指定另一配置文件。

适用于多个 Cloud Firestore 数据库的配置

运行 firebase init 时，您的 firebase.json 文件将包含一个与项目的默认数据库相对应的 firestore 键，如上所示。

如果您的项目包含多个 Cloud Firestore 数据库，请修改 firebase.json 文件，将不同的 Cloud Firestore Security Rules 和数据库索引源文件与每个数据库相关联。使用 JSON 数组修改该文件，每个数据库对应一个条目。

      "firestore": [
        {
          "database": "(default)",
          "rules": "firestore.default.rules",
          "indexes": "firestore.default.indexes.json"
        },
        {
          "database": "ecommerce",
          "rules": "firestore.ecommerce.rules",
          "indexes": "firestore.ecommerce.indexes.json"
        }
      ],

在部署时要忽略的 Cloud Functions 文件

在部署函数时，CLI 会自动指定 functions 目录中要忽略的文件列表。这样可以避免将无关的文件部署到后端，这类文件可能会增加部署的数据大小。

下面是默认忽略的文件列表（以 JSON 格式显示）：

"ignore": [
  ".git",
  ".runtimeconfig.json",
  "firebase-debug.log",
  "firebase-debug.*.log",
  "node_modules"
]

如果您在 firebase.json 中为 ignore 添加自己的自定义值，请务必保留上面显示的文件列表（如果缺失，请添加）。

管理项目别名

您可以将多个 Firebase 项目与同一个项目目录相关联。例如，您可能希望将一个 Firebase 项目用于预演环境，将另一个 Firebase 项目用于生产环境。使用不同的项目环境，您可以在将更改部署到生产环境之前进行验证。使用 firebase use 命令，您可以在别名之间切换，也可以创建新别名。

添加项目别名

当您在项目初始化期间选择 Firebase 项目时，系统会自动为该项目分配 default 别名。但是，如需允许针对不同的 Firebase 项目运行项目专有命令，但却使用同一个项目目录，请在项目目录中运行以下命令：

firebase use --add

此命令会提示您选择另一个 Firebase 项目，并为该项目分配一个别名。分配的别名会写入项目目录中的 .firebaserc 文件。

使用项目别名

如需使用已分配的 Firebase 项目别名，请在项目目录中运行以下任一命令。

您可以通过向任何 CLI 命令传递 --project 标志来替换用作当前活跃项目的项目。例如，您可以将 CLI 设置为针对已为其分配 staging 别名的 Firebase 项目运行。如果您要针对已为其分配 prod 别名的 Firebase 项目运行单个命令，则可以运行 firebase deploy --project=prod 之类的命令。

源代码控制和项目别名

通常情况下，您应将 .firebaserc 文件签入源代码控制系统，以允许您的团队共用项目别名。但是，对于开源项目或起始模板，您通常不应签入 .firebaserc 文件。

如果您的开发项目专供自己使用，您可以在每个命令中传递 --project 标志，也可以运行 firebase use PROJECT_ID，而无需为 Firebase 项目分配别名。

在本地提供并测试您的 Firebase 项目

您可以在将 Firebase 项目部署到生产环境之前，先在本地托管的网址中查看并测试该项目。如果您只想测试选定功能，则可以在 firebase serve 命令的标志中使用英文逗号分隔列表。

如果您想执行以下任一任务，请在本地项目目录的根目录中运行以下命令：

• 查看 Firebase 托管应用的静态内容。
• 使用 Cloud Functions 为 Firebase Hosting 生成动态内容，并且您想要使用生产（已部署）HTTP 函数在本地网址上模拟 Hosting。

firebase serve --only hosting

使用本地 HTTP 函数模拟您的项目

在项目目录中运行以下任一命令，以使用本地 HTTP 函数模拟您的项目。

• 如需在本地网址上模拟 HTTP 函数和托管内容以便进行测试，请使用以下任一命令：

  firebase serve

  firebase serve --only functions,hosting // uses a flag

• 如需仅模拟 HTTP 函数，请使用以下命令：

  firebase serve --only functions

通过其他本地设备进行测试

默认情况下，firebase serve 仅响应来自 localhost 的请求。这意味着您可以通过计算机的网络浏览器访问托管内容，但不能通过网络中的其他设备访问托管内容。如果您想要通过其他本地设备进行测试，请使用 --host 标志，如下所示：

firebase serve --host 0.0.0.0  // accepts requests to any host

部署到 Firebase 项目

Firebase CLI 负责管理将代码和资源部署到 Firebase 项目的工作，包括：

• Firebase Hosting 网站的新版本
• 全新的、经过更新的或现有的 Cloud Functions for Firebase
• 针对 Firebase Data Connect 新增或更新的架构和连接器
• Firebase Realtime Database 的规则
• Cloud Storage for Firebase 的规则
• Cloud Firestore 的规则
• Cloud Firestore 的索引

如需部署至 Firebase 项目，请在项目目录下运行以下命令：

firebase deploy

您可以选择向每个部署添加注释。此注释将与项目的“Firebase Hosting”页面上的其他部署信息一起显示。例如：

firebase deploy -m "Deploying the best new feature ever."

使用 firebase deploy 命令时，请注意以下事项：

• 如需从项目目录部署资源，该项目目录必须包含 firebase.json 文件。firebase init 命令已自动为您创建此文件。

• 默认情况下，firebase deploy 会为项目目录中所有可部署的资源创建一个版本。如需部署特定的 Firebase 服务或功能，请使用部分部署。

安全规则的部署冲突

对于 Firebase Realtime Database、Cloud Storage for Firebase 和 Cloud Firestore，您可以在本地项目目录或 Firebase 控制台中定义安全规则。

避免部署冲突的另一个方法是使用部分部署，并且仅在 Firebase 控制台中定义规则。

部署配额

您可能会超出 Firebase 部署操作的速率或用量配额（虽然这种情况不太可能发生）。例如，部署大量函数时，您可能会收到 HTTP 429 Quota 错误消息。如需解决此类问题，请尝试使用部分部署。

回滚部署

您可以从项目的“Firebase Hosting”页面回滚 Firebase Hosting 部署，只需为所需的版本选择回滚操作即可。

目前，您无法回滚 Firebase Realtime Database、Cloud Storage for Firebase 或 Cloud Firestore 的安全规则版本。

部署特定的 Firebase 服务

如果您只想部署特定的 Firebase 服务或功能，则可以在 firebase deploy 命令的标志中使用英文逗号分隔的列表。例如，以下命令会部署 Firebase Hosting 内容和 Cloud Storage 安全规则。

firebase deploy --only hosting,storage

下表列出了可部分部署的服务和功能。这些标志中的名称对应于 firebase.json 配置文件中的键。

部署特定函数

部署函数时，您可以针对具体的函数。例如：

firebase deploy --only functions:function1

firebase deploy --only functions:function1,functions:function2

另一种方法是在 /functions/index.js 文件中将函数整理为不同的导出组。将函数分组可让您使用单个命令部署多个函数。

例如，您可以编写以下函数来定义 groupA 和 groupB：

var functions = require('firebase-functions/v1');

exports.groupA = {
  function1: functions.https.onRequest(...),
  function2: functions.database.ref('\path').onWrite(...)
}
exports.groupB = require('./groupB');

在此示例中，一个单独的 functions/groupB.js 文件包含用于具体定义 groupB 中函数的其他函数。例如：

var functions = require('firebase-functions/v1');

exports.function3 = functions.storage.object().onChange(...);
exports.function4 = functions.analytics.event('in_app_purchase').onLog(...);

在此示例中，您可以在项目目录下运行以下命令来部署所有 groupA 函数：

firebase deploy --only functions:groupA

或者，您也可以运行以下命令来部署一个组中的特定函数：

firebase deploy --only functions:groupA.function1,groupB.function4

删除函数

Firebase CLI 支持以下命令和选项，供您删除以前部署的函数：

• 删除所有区域中与指定名称匹配的所有函数：

  firebase functions:delete FUNCTION-1_NAME

• 删除在非默认区域中运行的指定函数：

  firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

• 删除多个函数：

  firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

• 删除指定的函数组：

  firebase functions:delete GROUP_NAME

• 忽略确认提示：

  firebase functions:delete FUNCTION-1_NAME --force

设置部署前和部署后脚本任务

您可以将 shell 脚本关联到 firebase deploy 命令，以执行部署前任务或部署后任务。例如，部署前脚本可以将 TypeScript 代码转译为 JavaScript，而部署后钩子可以让管理员知道系统向 Firebase Hosting 部署了新的网站内容。

如需设置部署前钩子或部署后钩子，请将 bash 脚本添加到您的 firebase.json 配置文件中。您可以直接在 firebase.json 文件中定义简短的脚本，也可以引用项目目录中的其他文件。

例如，以下脚本是某个部署后任务的 firebase.json 表达式，该任务会在成功部署至 Firebase Hosting 时发送 Slack 消息。

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

messageSlack.sh 脚本文件位于项目目录中，内容类似于：

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://SLACK_WEBHOOK_URL

您可以为任何可部署的资源设置 predeploy 和 postdeploy 钩子。请注意，运行 firebase deploy 会触发在 firebase.json 文件中定义的所有部署前任务和部署后任务。如需仅运行那些与特定 Firebase 服务关联的任务，请使用部分部署命令。

predeploy 和 postdeploy 钩子都会将脚本的标准输出和错误流显示在终端上。如果出现故障，请注意以下事项：

• 如果部署前钩子未能按预期完成，则部署会取消。
• 无论部署因何种原因失败，都不会触发部署后钩子。

环境变量

在部署前钩子和部署后钩子中运行的脚本内，可以使用以下环境变量：

• $GCLOUD_PROJECT：活跃项目的 ID
• $PROJECT_DIR：包含 firebase.json 文件的根目录
• $RESOURCE_DIR：（仅适用于 hosting 和 functions 脚本）要部署的 Hosting 资源或 Cloud Functions 资源所在目录的位置

管理多个 Realtime Database 实例

一个 Firebase 项目可以拥有多个 Firebase Realtime Database 实例。默认情况下，CLI 命令与您的默认数据库实例进行交互。

但是，您可以使用 --instance DATABASE_NAME 标记与非默认数据库实例进行交互。以下命令支持 --instance 标记：

• firebase database:get
• firebase database:profile
• firebase database:push
• firebase database:remove
• firebase database:set
• firebase database:update

命令参考

CLI 管理命令

项目管理命令

部署和本地开发

使用以下命令，您可以部署 Firebase Hosting 网站并与之进行互动。

App Distribution 命令

App Hosting 命令

Authentication（用户管理）命令

Cloud Firestore 命令

Cloud Functions for Firebase 命令

如需了解详情，请参阅环境配置文档。

Crashlytics 命令

Data Connect 命令

Data Connect CLI 参考指南中详细介绍了这些命令及其用例。

Extensions 命令

Extensions 发布方命令

Hosting 命令

Realtime Database 命令

请注意，您可以通过 Firebase 控制台或者使用通用 firebase init 工作流或特定的 firebase init database 流程创建初始默认 Realtime Database 实例。

实例创建后，您可以按照管理多个 Realtime Database 实例中所述对其进行管理。

Remote Config 命令