Firebase CLI 参考

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

设置

您必须先在计算机上安装 Node.js,然后才能安装 Firebase CLI。安装 Node.js 之后,您便可以运行以下命令,使用 Node 软件包管理器 (NPM) 安装 Firebase CLI:

npm install -g firebase-tools

您现在应该就有了一个全局可用的 Firebase 命令,可从您计算机上的任何终端窗口运行。安装 Firebase CLI 后,请使用您的 Google 帐号登录:

firebase login

此命令将您的本地计算机连接上 Firebase 帐号,并授予对您项目的访问权限。要测试身份验证是否有效,您可以运行 firebase list,查看您所有 Firebase 项目的列表。此列表应与 Firebase 控制台中的项目列表相同。

获取最新版本

您可以重新运行安装命令,以确保 Firebase CLI 为最新版本:

npm install -g firebase-tools

初始化 Firebase 项目

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

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

firebase init

firebase init 命令将引导您逐步设置项目目录,包括让您选择所需的 Firebase 服务,然后为所选服务配置特定的文件。如果您稍后想添加其他 Firebase 服务,只需再次运行 firebase init 即可。

初始化过程还会要求您选择默认的 Firebase 项目。此步骤会将当前项目目录与一个 Firebase 项目相关联,以便针对相应的 Firebase 项目运行项目专有命令(如 firebase deploy)。您还可以将同一项目目录与多个 Firebase 项目关联(如调试版项目和正式版项目)。

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 serve 命令的标志中使用逗号分隔列表。

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

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

    firebase serve
    firebase serve --only functions,hosting // uses a flag
  • 要仅模拟 HTTP 函数,请使用以下命令:

    firebase serve --only functions

如果您想执行以下任一操作,请在项目目录下运行以下命令:

firebase serve --only hosting

部署到 Firebase 项目

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

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

要部署至 Firebase 项目,请在项目目录下运行以下命令:

firebase deploy

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

请注意,要从项目目录部署资源,则项目目录必须具有 firebase.json 文件。firebase init 命令已自动为您创建此文件。

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

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

安全规则的部署冲突

对于 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

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

predeploypostdeploy 钩子都会将脚本的标准输出和错误流显示在终端上。如果任务执行失败,请注意:

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

环境变量

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

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

管理项目别名

您可以将多个 Firebase 项目与同一项目目录相关联。例如,您可能需要将一个 Firebase 项目用于调试环境,将另一个 Firebase 项目用于生产环境。通过使用不同的项目环境,您可以在向生产环境部署资源之前验证更改。通过 firebase use 命令,您可以切换别名,并能新建别名。

添加项目别名

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

firebase use --add

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

使用项目别名

要使用已定义的 Firebase 项目别名,请在项目目录中运行以下某个命令。

命令 说明
firebase use 查看您项目目录中当前定义的别名列表
firebase use alias_or_project-id 在项目目录的别名之间切换
firebase use --clear 清除目前“正在使用”的别名,并指示所有命令都应用到 default 别名
firebase use --unalias alias 从项目目录中移除别名

使用别名时,所有项目专有命令(如 firebase deployfirebase data:get)将针对当前“使用”的 Firebase 项目运行。如果项目目录中只定义了一个别名,则所有项目专有命令都将自动针对该别名运行。

源代码控制和 Firebase 项目别名

通常情况下,您应将 .firebaserc 文件签入源代码控制系统。这样一来,您的团队就可以共享常用的项目别名。但是,对于开放源代码项目或起始模板,您通常不应签入 .firebaserc 文件。

如果开发项目专供您自己使用,您可以在每个命令中传递 --project 标志,也可以运行 firebase use project-id,而不为 Firebase 项目定义别名。

管理多个 Firebase 实时数据库实例

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

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

命令
database:profile
database:remove
database:push
database:set
database:update
database:get

命令参考

管理命令

命令 说明
login 对您的 Firebase 帐号进行身份验证。需要用到网络浏览器。
logout 退出 Firebase CLI。
login:ci 生成可用于非互动环境的身份验证令牌。
list 打印包含您所有 Firebase 项目的列表。
use 设置活跃 Firebase 项目,管理项目别名。
open 迅速打开浏览器,以显示相关的项目资源。
init 在当前目录中新建一个 Firebase 项目。此命令会在当前目录中创建 firebase.json 配置文件。
help 显示 CLI 或特定命令的帮助信息。

部署和本地开发

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

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

数据库命令

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

托管命令

命令 说明
hosting:disable 停止针对活跃项目投放 Firebase 托管流量。运行此命令后,在转到您项目的托管网址时,会看到“找不到网站”消息。

Cloud Firestore 命令

命令 说明
firestore:delete 删除 Cloud Firestore 中的文档。借助 Firebase CLI,您可以使用递归删除来删除某个集合中的所有文档。

Cloud Functions 命令

命令 说明
functions:log 从部署的 Cloud Functions 中读取日志。
functions:config:set 存储当前项目的 Cloud Functions 的运行时配置值。
functions:config:get 检索当前项目的 Cloud Functions 的现有配置值。
functions:config:unset 从当前项目的运行时配置中移除值。
functions:config:clone 将运行时配置从一个项目环境复制到另一个项目环境。

有关详细信息,请参阅环境配置

用户管理命令

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

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面