Vai alla console

Firebase CLI 参考文档

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

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

设置或更新 CLI

安装 Firebase CLI

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

Windows MacOS Linux

Windows

您可以使用以下选项之一安装 Windows 版 Firebase CLI:

选项 说明 推荐用途
独立二进制文件 下载 CLI 的独立二进制文件。然后,您可以访问可执行文件以打开 shell,在其中可以运行 firebase 命令。 新开发者
未使用过或不熟悉 Node.js 的开发者
npm 使用 npm (Node Package Manager) 安装 CLI 并启用全局可用的 firebase 命令。 使用 Node.js 的开发者

独立二进制文件

如需下载并运行 Firebase CLI 的二进制文件,请按以下步骤操作:

  1. 下载 Windows 版 Firebase CLI 二进制文件

  2. 访问二进制文件以打开 shell,在其中可以运行 firebase 命令。

  3. 继续登录并测试 CLI

npm

如需使用 npm (Node Package Manager) 安装 Firebase CLI,请按以下步骤操作:

  1. 使用 nvm-windows (Node Version Manager) 安装 Node.js。安装 Node.js 时会自动安装 npm 命令工具。

  2. 运行以下命令以使用 npm 安装 Firebase CLI:

    npm install -g firebase-tools

    此命令会启用全局可用的 firebase 命令。

  3. 继续登录并测试 CLI

Mac OS 或 Linux

您可以使用以下选项之一安装 Mac OS 版 Firebase CLI 或 Linux 版 Firebase CLI:

选项 说明 推荐用途
自动安装脚本 运行一条命令来自动检测您的操作系统,下载最新的 CLI 版本,然后启用全局可用的 firebase 命令。 新开发者
未使用过或不熟悉 Node.js 的开发者 在 CI/CD 环境中自动部署
独立二进制文件 下载 CLI 的独立二进制文件。然后,您可以按照适合自己的工作流的方式配置并运行二进制文件。 可以使用 CLI 完全自定义的工作流
npm 使用 npm (Node Package Manager) 安装 CLI 并启用全局可用的 firebase 命令。 使用 Node.js 的开发者

自动安装脚本

如需使用自动安装脚本安装 Firebase CLI,请按以下步骤操作:

  1. 运行以下 cURL 命令:

    curl -sL firebase.tools | bash

    该脚本会自动检测您的操作系统,下载最新 Firebase CLI 版本,然后启用全局可用的 firebase 命令。

  2. 继续登录并测试 CLI

如需了解自动安装脚本的更多示例和详细信息,请参阅 firebase.tools 上的脚本源代码。

独立二进制文件

如需下载并运行适用于您的操作系统的 Firebase CLI 二进制文件,请按以下步骤操作:

  1. 下载适用于您的操作系统的 Firebase CLI 二进制文件:Mac OS | Linux

  2. (可选)设置全局可用的 firebase 命令。

    1. 运行 chmod +x ./firebase_tools,将该二进制文件转为可执行文件。
    2. 将该二进制文件的路径添加到您的 PATH 环境变量中。
  3. 继续登录并测试 CLI

npm

如需使用 npm (Node Package Manager) 安装 Firebase CLI,请按以下步骤操作:

  1. 使用 nvm (Node Version Manager) 安装 Node.js
    安装 Node.js 时会自动安装 npm 命令工具。

  2. 运行以下命令以使用 npm 安装 Firebase CLI:

    npm install -g firebase-tools

    此命令会启用全局可用的 firebase 命令。

  3. 继续登录并测试 CLI

登录并测试 Firebase CLI

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

  1. 运行以下命令以使用您的 Google 帐号登录 Firebase:

    firebase login

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

  2. 通过列出 Firebase 项目来测试 CLI 是否已正确安装,并访问您的帐号:运行以下命令:

    firebase list

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

更新到最新 CLI 版本

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

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

Windows

  • 独立二进制文件下载新版本,然后安装新版本来替换系统上的旧版本
  • npm:运行 npm install -g firebase-tools

Mac OS

  • 自动安装脚本:运行 curl -sL firebase.tools | bash
  • 独立二进制文件下载新版本,然后安装新版本来替换系统上的旧版本
  • npm:运行 npm install -g firebase-tools

Linux

  • 自动安装脚本:运行 curl -sL firebase.tools | bash
  • 独立二进制文件下载新版本,然后安装新版本来替换系统上的旧版本
  • npm:运行 npm install -g firebase-tools

将 CLI 与 CI 系统配合使用

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

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

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

    firebase login:ci
  3. 访问所提供的网址,然后使用 Google 帐号登录。

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

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

  6. 在运行 firebase 命令时使用此令牌。您可以使用以下两个选项之一:

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

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

初始化 Firebase 项目

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

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

firebase init

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

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

    此步骤提示您为所选产品的特定文件设置配置。如需详细了解这些配置,请参阅具体产品的文档(例如托管)。请注意,您以后可以随时运行 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 托管选项。但是,对于其他可以使用 Firebase CLI 部署的 Firebase 服务firebase init 命令会创建特定文件(例如,用于 Cloud Functions 函数的 index.js 文件),您可以在其中为这些服务定义相关设置。您还可以在 firebase.json 文件中设置部署前钩子或部署后钩子

下面是包含默认设置的示例 firebase.json 文件(如果您在初始化期间选择 Firebase 托管、Cloud Firestore 和 Cloud Functions for Firebase)。

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

管理项目别名

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

添加项目别名

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

firebase use --add

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

使用项目别名

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

命令 说明
firebase use 查看项目目录中当前定义的别名列表
firebase use \
project_id_or_alias
针对指定的 Firebase 项目运行所有命令。
CLI 将此项目用作当前“活跃项目”。
firebase use --clear 针对分配有 default 别名的 Firebase 项目运行所有命令。
CLI 将此项目用作当前“活跃项目”。

运行此命令与运行 firebase use default 相同。

firebase use \
--unalias project_alias
从项目目录中移除别名。

您可以通过向任何 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 托管生成动态内容,并且您想要使用生产(已部署)HTTP 函数在本地网址上模拟 Firebase 托管。
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 的请求。这意味着您可以通过计算机的 Web 浏览器访问托管内容,但不能通过网络中的其他设备访问托管内容。如果您想要通过其他本地设备进行测试,请使用 --host 标志,如下所示:

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

部署到 Firebase 项目

Firebase CLI 负责管理将代码和资源部署到您的 Firebase 项目,包括:

  • Firebase 托管网站的新版本
  • 全新的、经过更新的或现有的 Cloud Functions for Firebase
  • Firebase 实时数据库的规则
  • Cloud Storage for Firebase 的规则
  • Cloud Firestore 的规则
  • Cloud Firestore 的索引

如需部署到 Firebase 项目,请在项目目录下运行以下命令:

firebase deploy

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

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

使用 firebase deploy 命令时,请注意以下事项:

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

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

安全规则的部署冲突

对于 Firebase 实时数据库、Cloud Storage for Firebase 和 Cloud Firestore,您可以在本地项目目录或 Firebase 控制台中定义安全规则。

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

部署配额

您可能会超出 Firebase 部署操作的速率或用量配额(虽然这种情况不太可能发生)。例如,部署大量函数时,您可能会收到 HTTP 429 Quota 错误消息。如需解决此类问题,请尝试针对特定 Firebase 服务使用部分部署申请增加配额。例如,名为每位用户每 100 秒的写入请求次数的配额可能有助于解决上面提及的 Cloud Functions 函数 429 错误。

回滚部署

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

目前,您无法回滚 Firebase 实时数据库、Cloud Storage for Firebase 或 Cloud Firestore 的安全规则的版本。

部署特定的 Firebase 服务

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

firebase deploy --only hosting,storage

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

标志语法 部署的服务或功能
--only hosting Firebase 托管内容
--only database Firebase 实时数据库规则
--only storage Cloud Storage for Firebase 规则
--only firestore Cloud Firestore 规则和索引
--only firestore:rules Cloud Firestore 规则
--only firestore:indexes Cloud Firestore 索引
--only functions Cloud Functions for Firebase(可以使用此标志更有针对性的版本

部署特定函数

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

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

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

例如,您可以编写以下函数来定义 groupAgroupB

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

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');

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 function1-name

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

    firebase functions:delete function1-name --region region-name

  • 删除多个函数:

    firebase functions:delete function1-name function2-name

  • 删除指定的函数组:

    firebase functions:delete group-name

  • 忽略确认提示:

    firebase functions:delete function1-name --force

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

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

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

例如,以下脚本是某个部署后任务的 firebase.json 表达式,该任务会在成功部署至 Firebase 托管时发送 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

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

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

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

环境变量

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

  • $GCLOUD_PROJECT:活跃项目的 ID
  • $PROJECT_DIR:包含 firebase.json 文件的根目录
  • $RESOURCE_DIR:(仅适用于 hostingfunctions 脚本)要部署的 Firebase 托管资源或 Cloud Functions 函数资源所在目录的位置

管理多个实时数据库实例

如果单个项目具有多个 Firebase 实时数据库实例,请使用 --instance instance-name 选项与非默认数据库实例 instance-name.firebaseio.com 进行交互。

以下命令支持 --instance 选项:

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

命令参考

CLI 管理命令

命令 说明
帮助 显示 CLI 或特定命令的帮助信息。
init 在当前目录中关联并设置一个新的 Firebase 项目。此命令会在当前目录中创建 firebase.json 配置文件。
list 已弃用。应改为使用 projects:list
列出您有权访问的所有 Firebase 项目。
login 对 CLI 进行身份验证以登录 Firebase 帐号。需要用到 Web 浏览器。
login:ci 生成可用于非交互环境的身份验证令牌。
logout 将 CLI 从 Firebase 帐号退出登录。
open 打开浏览器,以显示相关的项目资源。
projects:list 列出您有权访问的所有 Firebase 项目。
use 为 CLI 设置活跃 Firebase 项目。
管理项目别名

项目管理命令

命令 说明
apps:create 在活跃项目中创建一个新的 Firebase 应用。
apps:list 列出活跃项目中已注册的 Firebase 应用。
apps:sdkconfig 输出 Firebase 应用的 Google 服务配置。
projects:addfirebase 将 Firebase 资源添加到现有 Google Cloud Platform (GCP) 项目。
projects:create 创建新的 Google Cloud Platform (GCP) 项目,然后将 Firebase 资源添加到新项目。
projects:list 列出您有权访问的所有 Firebase 项目。
setup:web 已弃用。应改为使用 apps:sdkconfig 并指定 web 作为平台参数
输出 Firebase Web 应用的 Google 服务配置。

部署和本地开发

使用以下命令,您可以部署 Firebase 托管网站并与之进行交互。

命令 说明
deploy 将项目目录中的代码和资源部署到活跃项目。对于 Firebase 托管,需要有 firebase.json 配置文件。
serve 根据 Firebase 托管配置,启动一个本地 Web 服务器。对于 Firebase 托管,需要有 firebase.json 配置文件。

应用分发命令

命令 说明
appdistribution:distribute \
--app firebase-app-id
让测试人员可以访问此构建版本。

身份验证(用户管理)命令

命令 说明
auth:export 将活跃项目的用户帐号导出至 JSON 或 CSV 文件。如需了解详情,请参阅 auth:import 和 auth:export 页面
auth:import 将用户帐号从 JSON 或 CSV 文件导入到活跃项目。如需了解详情,请参阅 auth:import 和 auth:export 页面

Cloud Firestore 命令

命令 说明
firestore:delete 删除活跃项目的数据库中的文档。借助 CLI,您可以递归删除某个集合中的所有文档。

Cloud Functions for Firebase 命令

命令 说明
functions:config:clone 将另一个项目的环境克隆到活跃 Firebase 项目。
functions:config:get 检索活跃项目的 Cloud Functions 函数的现有配置值。
functions:config:set 存储活跃项目的 Cloud Functions 函数的运行时配置值。
functions:config:unset 从活跃项目的运行时配置中移除值。
functions:log 从已部署的 Cloud Functions 函数中读取日志。

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

扩展程序命令

命令 说明
ext 显示有关如何使用 Firebase 扩展程序命令的信息。
列出安装在活跃项目中的扩展程序。
ext:configure \
extension-instance-id
启动工作流以重新配置已安装扩展程序的参数值。
ext:info \
extension-name
输出有关官方 Firebase 扩展程序的详细信息。
ext:install \
extension-name
启动工作流以将官方 Firebase 扩展程序安装到您的 Firebase 项目中。
ext:list 列出安装在 Firebase 项目中的所有扩展程序。
输出每个扩展程序的实例 ID。
ext:uninstall \
extension-instance-id
从 Firebase 项目中卸载扩展程序。
ext:update \
extension-instance-id
启动工作流以将已安装的扩展程序更新为最新版本。

托管命令

命令 说明
hosting:disable 停止为活跃 Firebase 项目的 Firebase 托管流量提供服务。运行此命令后,您的项目的托管网址将显示“找不到网站”消息。

实时数据库命令

命令 说明
database:get 从活跃项目的数据库中提取数据,并以 JSON 格式显示这些数据。支持查询已编入索引的数据。
database:profile 在活跃项目的数据库上构建操作配置文件。如需了解详情,请参阅实时数据库操作类型
database:push 将新数据推送到活跃项目的数据库中指定位置处的列表。从文件、STDIN 或命令行参数中获取输入。
database:remove 删除活跃项目的数据库中指定位置处的所有数据。
database:set 替换活跃项目的数据库中指定位置处的所有数据。从文件、STDIN 或命令行参数中获取输入。
database:update 在活跃项目的数据库中的指定位置处执行部分更新。从文件、STDIN 或命令行参数中获取输入。