firebase-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

firebase-cli — Firebase Command Line Interface

firebase-cli — Firebase命令行界面

Keyword:
firebase
·
firebase deploy
·
firebase init
·
firebase emulators
The Firebase CLI (
firebase-tools
) manages your Firebase project from the terminal: deploy, emulate, import/export data, manage users, configure services, and automate CI/CD.

关键词：
firebase
·
firebase deploy
·
firebase init
·
firebase emulators
Firebase CLI（
firebase-tools
）可通过终端管理你的Firebase项目：部署、模拟、导入/导出数据、管理用户、配置服务以及自动化CI/CD。

When to use this skill

何时使用该技能

Deploy Firebase Hosting, Cloud Functions, Firestore rules/indexes, Realtime Database rules, Cloud Storage rules, Remote Config, or Extensions
Set up a new Firebase project with
```
firebase init
```
Run the Firebase Emulator Suite locally for development and testing
Manage preview/staging channels for Hosting
Import or export Firebase Authentication users in bulk
Distribute app builds to testers via App Distribution
Manage Firebase Extensions (install, configure, update, uninstall)
Deploy Next.js / Angular apps via Firebase App Hosting
Use Firebase CLI in CI/CD pipelines with service account credentials

部署Firebase Hosting、Cloud Functions、Firestore规则/索引、Realtime Database规则、Cloud Storage规则、Remote Config或Extensions
使用
```
firebase init
```
搭建新的Firebase项目
本地运行Firebase Emulator Suite进行开发和测试
管理Hosting的预览/预发布渠道
批量导入或导出Firebase Authentication用户
通过App Distribution向测试人员分发应用构建版本
管理Firebase Extensions（安装、配置、更新、卸载）
通过Firebase App Hosting部署Next.js / Angular应用
在CI/CD流水线中使用服务账号凭据运行Firebase CLI

Instructions

操作步骤

Install the Firebase CLI:
```
npm install -g firebase-tools
```

Authenticate:

firebase login

(browser OAuth) or

GOOGLE_APPLICATION_CREDENTIALS

for CI

Initialize project:
```
firebase init
```
(creates
```
firebase.json
```
and
```
.firebaserc
```
)

Deploy:

firebase deploy

firebase deploy --only hosting,functions

Run emulators:
```
firebase emulators:start
```
For detailed command reference, see references/commands.md
For installation and setup scripts, see scripts/install.sh

CI/CD: Use
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json firebase deploy
instead of the deprecated
--token
/
FIREBASE_TOKEN
method.

安装Firebase CLI：
```
npm install -g firebase-tools
```
身份验证：使用
```
firebase login
```
（浏览器OAuth）或在CI环境中使用
```
GOOGLE_APPLICATION_CREDENTIALS
```
初始化项目：
```
firebase init
```
（会生成
```
firebase.json
```
和
```
.firebaserc
```
）

部署：

firebase deploy

或

firebase deploy --only hosting,functions

运行模拟器：
```
firebase emulators:start
```
如需详细命令参考，请查看references/commands.md
如需安装和设置脚本，请查看scripts/install.sh

CI/CD说明：使用
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json firebase deploy
替代已弃用的
--token
/
FIREBASE_TOKEN
方式。

Examples

示例

Deploy everything

部署所有资源

bash

firebase deploy

bash

firebase deploy

Deploy only Hosting and Functions

仅部署Hosting和Functions

bash

firebase deploy --only hosting,functions

bash

firebase deploy --only hosting,functions

Run all emulators with data persistence

运行所有模拟器并保留数据

bash

firebase emulators:start --import ./emulator-data --export-on-exit

bash

firebase emulators:start --import ./emulator-data --export-on-exit

Create a preview channel and deploy

创建预览渠道并部署

bash

firebase hosting:channel:create staging --expires 7d
firebase hosting:channel:deploy staging

bash

firebase hosting:channel:create staging --expires 7d
firebase hosting:channel:deploy staging

Import users from JSON

从JSON导入用户

bash

firebase auth:import users.json --hash-algo=BCRYPT

bash

firebase auth:import users.json --hash-algo=BCRYPT

Distribute Android build to testers

向测试人员分发Android构建版本

bash

firebase appdistribution:distribute app-release.apk \
  --app "1:1234567890:android:abcd1234" \
  --release-notes "Sprint 42 build" \
  --groups "qa-team"

bash

firebase appdistribution:distribute app-release.apk \
  --app "1:1234567890:android:abcd1234" \
  --release-notes "Sprint 42构建版本" \
  --groups "qa-team"

Quick Start

快速开始

bash

undefined

bash

undefined

Install

安装

npm install -g firebase-tools

Authenticate

身份验证

firebase login

Initialize project (interactive)

初始化项目（交互式）

firebase init

Deploy

部署

firebase deploy

Run emulators

运行模拟器

firebase emulators:start

---

firebase emulators:start

---

Installation

安装方式

npm (recommended — all platforms)

npm（推荐 — 全平台支持）

bash

npm install -g firebase-tools
firebase --version

bash

npm install -g firebase-tools
firebase --version

Standalone binary (macOS/Linux — no Node.js required)

独立二进制文件（macOS/Linux — 无需Node.js）

bash

curl -sL firebase.tools | bash

bash

curl -sL firebase.tools | bash

CI/CD — service account authentication (recommended)

CI/CD — 服务账号身份验证（推荐）

bash

undefined

bash

undefined

Set environment variable pointing to service account JSON key

设置指向服务账号JSON密钥的环境变量

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json" firebase deploy --non-interactive

undefined

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json" firebase deploy --non-interactive

undefined

Via skill script

通过技能脚本安装

bash

bash scripts/install.sh

bash

bash scripts/install.sh

Core Usage

核心用法

Authentication

身份验证

bash

firebase login                          # OAuth browser login
firebase login --no-localhost           # Copy-paste code flow
firebase login:ci                       # Generate CI token (deprecated — use service account)
firebase login:list                     # List all authorized accounts
firebase login:use user@example.com     # Set default account
firebase logout                         # Sign out

bash

firebase login                          # OAuth浏览器登录
firebase login --no-localhost           # 复制粘贴代码流程
firebase login:ci                       # 生成CI令牌（已弃用 — 使用服务账号）
firebase login:list                     # 列出所有已授权账号
firebase login:use user@example.com     # 设置默认账号
firebase logout                         # 登出

Project Management

项目管理

bash

firebase init                    # Set up Firebase features in current directory
firebase use <project_id>        # Set active project
firebase use --add               # Add a project alias
firebase projects:list           # List all Firebase projects
firebase open hosting:site       # Open Firebase console in browser

bash

firebase init                    # 在当前目录中设置Firebase功能
firebase use <project_id>        # 设置活跃项目
firebase use --add               # 添加项目别名
firebase projects:list           # 列出所有Firebase项目
firebase open hosting:site       # 在浏览器中打开Firebase控制台

Deployment

部署

bash

undefined

bash

undefined

Deploy everything

部署所有资源

firebase deploy

Deploy specific targets

部署指定目标

firebase deploy --only hosting firebase deploy --only functions firebase deploy --only firestore firebase deploy --only hosting,functions

Deploy sub-targets

部署子目标

firebase deploy --only functions:myFunction firebase deploy --only hosting:my-site firebase deploy --only firestore:rules firebase deploy --only firestore:indexes

Exclude targets

排除指定目标

firebase deploy --except functions

With message

添加部署说明

firebase deploy --message "v2.3.1 release"

undefined

firebase deploy --message "v2.3.1版本发布"

undefined

Firebase Emulator Suite

Firebase模拟器套件

bash

undefined

bash

undefined

Start all configured emulators

启动所有已配置的模拟器

firebase emulators:start

Start specific emulators

启动指定模拟器

firebase emulators:start --only auth,firestore,functions

With data import/export

带数据导入/导出功能启动

firebase emulators:start --import ./emulator-data --export-on-exit

Run tests against emulators then shut down

针对模拟器运行测试后关闭

firebase emulators:exec "npm test" --only firestore,auth

Enable Functions debugger (Node.js inspector on port 9229)

启用Functions调试器（Node.js调试器在9229端口）

firebase emulators:start --inspect-functions

undefined

firebase emulators:start --inspect-functions

undefined

Local Development Server

本地开发服务器

bash

firebase serve                        # Hosting + HTTPS Functions
firebase serve --only hosting
firebase serve --port 5000

bash

firebase serve                        # Hosting + HTTPS Functions
firebase serve --only hosting
firebase serve --port 5000

Hosting Commands

Hosting命令

bash

undefined

bash

undefined

Preview channels

预览渠道

firebase hosting:channel:create staging --expires 7d firebase hosting:channel:deploy staging firebase hosting:channel:list firebase hosting:channel:open staging firebase hosting:channel:delete staging --force firebase hosting:clone my-app:live my-app-staging:staging

Multi-site management

多站点管理

firebase hosting:sites:list firebase hosting:sites:create new-site-id firebase hosting:disable --site my-old-site

---

firebase hosting:sites:list firebase hosting:sites:create new-site-id firebase hosting:disable --site my-old-site

---

Cloud Functions Commands

Cloud Functions命令

bash

firebase functions:list                           # List deployed functions
firebase functions:log                            # View logs
firebase functions:log --only myFunction          # Filter by function name
firebase functions:delete myFunction              # Delete a function
firebase functions:shell                          # Local interactive shell

bash

firebase functions:list                           # 列出已部署的函数
firebase functions:log                            # 查看日志
firebase functions:log --only myFunction          # 按函数名称过滤日志
firebase functions:delete myFunction              # 删除函数
firebase functions:shell                          # 本地交互式shell

Secrets (2nd gen — replaces functions:config)

密钥（第二代 — 替代functions:config）

firebase functions:secrets:set MY_SECRET firebase functions:secrets:get MY_SECRET firebase functions:secrets:prune

Config (1st gen only)

配置（仅第一代支持）

firebase functions:config:set api.key="VALUE" firebase functions:config:get

---

firebase functions:config:set api.key="VALUE" firebase functions:config:get

---

Firestore Commands

Firestore命令

bash

firebase firestore:delete /collection/doc --recursive
firebase firestore:indexes
firebase firestore:rules:get

bash

firebase firestore:delete /collection/doc --recursive
firebase firestore:indexes
firebase firestore:rules:get

Realtime Database Commands

Realtime Database命令

bash

firebase database:get /path --pretty
firebase database:set /path data.json
firebase database:push /messages --data '{"text":"Hello"}'
firebase database:update /users/uid --data '{"name":"New Name"}'
firebase database:remove /path --confirm
firebase database:profile --duration 30

bash

firebase database:get /path --pretty
firebase database:set /path data.json
firebase database:push /messages --data '{"text":"Hello"}'
firebase database:update /users/uid --data '{"name":"New Name"}'
firebase database:remove /path --confirm
firebase database:profile --duration 30

Auth Import / Export

Auth导入/导出

bash

undefined

bash

undefined

Export all users

导出所有用户

firebase auth:export users.json

Import users (BCRYPT hashes)

导入用户（BCRYPT哈希）

firebase auth:import users.json --hash-algo=BCRYPT

Import users (SCRYPT hashes — Firebase default)

导入用户（SCRYPT哈希 — Firebase默认）

firebase auth:import users.json
--hash-algo=SCRYPT
--hash-key=<base64-key>
--salt-separator=<base64-separator>
--rounds=8
--mem-cost=8

---

firebase auth:import users.json
--hash-algo=SCRYPT
--hash-key=<base64-key>
--salt-separator=<base64-separator>
--rounds=8
--mem-cost=8

---

Remote Config

bash

firebase remoteconfig:get
firebase remoteconfig:get --output config.json
firebase remoteconfig:versions:list --limit 20
firebase remoteconfig:rollback --version-number 5

bash

firebase remoteconfig:get
firebase remoteconfig:get --output config.json
firebase remoteconfig:versions:list --limit 20
firebase remoteconfig:rollback --version-number 5

App Distribution

bash

undefined

bash

undefined

Distribute Android APK

分发Android APK

firebase appdistribution:distribute app.apk
--app APP_ID
--release-notes "Bug fixes and improvements"
--testers "qa@example.com"
--groups "qa-team,beta-users"

firebase appdistribution:distribute app.apk
--app APP_ID
--release-notes "Bug修复与功能优化"
--testers "qa@example.com"
--groups "qa-team,beta-users"

Manage testers

管理测试人员

firebase appdistribution:testers:add alice@example.com --group-alias qa-team firebase appdistribution:testers:remove alice@example.com firebase appdistribution:groups:list

---

firebase appdistribution:testers:add alice@example.com --group-alias qa-team firebase appdistribution:testers:remove alice@example.com firebase appdistribution:groups:list

---

Extensions

bash

firebase ext:list
firebase ext:info firebase/delete-user-data
firebase ext:install firebase/delete-user-data
firebase ext:configure delete-user-data
firebase ext:update delete-user-data
firebase ext:uninstall delete-user-data
firebase ext:export

bash

firebase ext:list
firebase ext:info firebase/delete-user-data
firebase ext:install firebase/delete-user-data
firebase ext:configure delete-user-data
firebase ext:update delete-user-data
firebase ext:uninstall delete-user-data
firebase ext:export

App Hosting (Next.js / Angular)

App Hosting（Next.js / Angular）

bash

firebase init apphosting
firebase apphosting:backends:create --location us-central1
firebase apphosting:backends:list
firebase deploy --only apphosting
firebase apphosting:rollouts:create BACKEND_ID --git-branch main

bash

firebase init apphosting
firebase apphosting:backends:create --location us-central1
firebase apphosting:backends:list
firebase deploy --only apphosting
firebase apphosting:rollouts:create BACKEND_ID --git-branch main

Deploy Targets (multi-site / multi-instance)

部署目标（多站点/多实例）

bash

undefined

bash

undefined

Apply target name to a resource

为资源应用目标名称

firebase target:apply hosting prod-site my-app-prod firebase target:apply storage prod-bucket my-app-bucket firebase target:apply database default my-app-db

Use target in deploy

在部署时使用目标

firebase deploy --only hosting:prod-site

Clear targets

清除目标

firebase target:clear hosting prod-site

---

firebase target:clear hosting prod-site

---

Best practices

最佳实践

Use service accounts for CI/CD: Set
```
GOOGLE_APPLICATION_CREDENTIALS
```
instead of
```
--token
```
(deprecated).
Use
--only
in deploy: Never deploy everything blindly in production — always scope with
```
--only
```
.
Emulators for development: Always run
```
emulators:start
```
locally before deploying; use
```
--import
```
/
```
--export-on-exit
```
for persistence.
Preview channels before production: Use
```
hosting:channel:deploy
```
for staging reviews before
```
firebase deploy --only hosting
```
.
Secrets over functions:config: For Cloud Functions 2nd gen, use
```
functions:secrets:set
```
(Secret Manager) instead of deprecated
```
functions:config:set
```
.
--non-interactive
in scripts: Always add
```
--non-interactive
```
in automated scripts to avoid hanging on prompts.
.firebaserc
in VCS: Commit
```
.firebaserc
```
(project aliases) but add secrets and service account keys to
```
.gitignore
```
.
--debug
for troubleshooting: Run any failing command with
```
--debug
```
for verbose output.

CI/CD使用服务账号：设置
```
GOOGLE_APPLICATION_CREDENTIALS
```
替代已弃用的
```
--token
```
。
部署时使用
--only
：生产环境中绝不要盲目部署所有资源 — 始终使用
```
--only
```
指定范围。
开发时使用模拟器：部署前务必本地运行
```
emulators:start
```
；使用
```
--import
```
/
```
--export-on-exit
```
保留数据。
生产前使用预览渠道：在执行
```
firebase deploy --only hosting
```
前，使用
```
hosting:channel:deploy
```
进行预发布评审。
使用Secrets替代functions:config：对于第二代Cloud Functions，使用
```
functions:secrets:set
```
（Secret Manager）替代已弃用的
```
functions:config:set
```
。
脚本中添加
--non-interactive
：自动化脚本中务必添加
```
--non-interactive
```
，避免因等待输入而挂起。
将
.firebaserc
纳入版本控制：提交
```
.firebaserc
```
（项目别名），但将密钥和服务账号密钥添加到
```
.gitignore
```
。
故障排查使用
--debug
：运行失败的命令时添加
```
--debug
```
以查看详细输出。

Troubleshooting

故障排除

Issue	Solution
`command not found: firebase`	Run `npm install -g firebase-tools` ; check `npm bin -g` is in `PATH`
Authentication error in CI	Set `GOOGLE_APPLICATION_CREDENTIALS` to service account JSON path
`FIREBASE_TOKEN` warning	Migrate from token-based auth to service accounts
Deploy fails with permission error	Verify service account has required IAM roles (Firebase Admin, Cloud Functions Admin, etc.)
Emulators not starting	Check ports 4000/5000/5001/8080/9000/9099/9199 are available; run `lsof -i :<port>`
Functions deploy timeout	Use `--only functions:specificFunction` to deploy one at a time
Hosting deploy not reflecting changes	Check `firebase.json` `public` directory and `ignore` patterns
`ext:install` fails	Check extension ID format: `publisher/extension-id` ; try `--debug`
Database permission denied	Verify database rules and that CLI auth account has access

问题	解决方案
`command not found: firebase`	运行 `npm install -g firebase-tools` ；检查 `npm bin -g` 是否在 `PATH` 中
CI环境中身份验证失败	将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为服务账号JSON文件路径
`FIREBASE_TOKEN` 警告	从基于令牌的身份验证迁移到服务账号
部署因权限错误失败	验证服务账号是否拥有所需IAM角色（Firebase管理员、Cloud Functions管理员等）
模拟器无法启动	检查端口4000/5000/5001/8080/9000/9099/9199是否可用；运行 `lsof -i :<port>` 查看占用情况
Functions部署超时	使用 `--only functions:specificFunction` 逐个部署函数
Hosting部署后未生效	检查 `firebase.json` 中的 `public` 目录和 `ignore` 规则
`ext:install` 失败	检查扩展ID格式是否为 `publisher/extension-id` ；尝试添加 `--debug`
数据库权限被拒绝	验证数据库规则以及CLI身份验证账号是否拥有访问权限

References

参考资料

Firebase CLI Reference — official full command reference
Full Command Reference — complete options and flags for all commands
Install Scripts —
```
install.sh
```
(setup) ·
```
deploy.sh
```
(deployment helper) ·
```
emulators.sh
```
(emulator management)
firebase-tools GitHub — source code and changelog
Firebase CLI Release Notes — version history
Auth Import/Export Reference — hash algorithm details
Hosting Preview Channels — staging workflow
Emulator Suite Configuration — emulator setup

Firebase CLI Reference — 官方完整命令参考
Full Command Reference — 所有命令的完整选项和参数
Install Scripts —
```
install.sh
```
（安装脚本）·
```
deploy.sh
```
（部署辅助脚本）·
```
emulators.sh
```
（模拟器管理脚本）
firebase-tools GitHub — 源代码和更新日志
Firebase CLI Release Notes — 版本历史
Auth Import/Export Reference — 哈希算法详情
Hosting Preview Channels — 预发布工作流
Emulator Suite Configuration — 模拟器设置