firebase-cli — Firebase 命令行界面

关键词：firebase · firebase deploy · firebase init · firebase emulators

Firebase CLI (firebase-tools) 让您从终端管理 Firebase 项目：
部署、模拟、导入/导出数据、管理用户、配置服务以及自动化 CI/CD。

何时使用此技能

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

操作说明

1. 安装 Firebase CLI：npm install -g firebase-tools
2. 身份验证：firebase login（浏览器 OAuth）或为 CI 环境设置 GOOGLE_APPLICATION_CREDENTIALS
3. 初始化项目：firebase init（会创建 firebase.json 和 .firebaserc）
4. 部署：firebase deploy 或 firebase deploy --only hosting,functions
5. 运行模拟器：firebase emulators:start
6. 详细的命令参考，请查看 references/commands.md
7. 安装和设置脚本，请查看 scripts/install.sh

CI/CD：请使用 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json firebase deploy
而不是已弃用的 --token / FIREBASE_TOKEN 方法。

示例

部署所有内容

firebase deploy

仅部署 Hosting 和 Functions

firebase deploy --only hosting,functions

运行所有模拟器并持久化数据

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

创建预览渠道并部署

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

从 JSON 导入用户

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

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

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

快速开始

# 安装
npm install -g firebase-tools

# 身份验证
firebase login

# 初始化项目（交互式）
firebase init

# 部署
firebase deploy

# 运行模拟器
firebase emulators:start

安装

npm（推荐 — 所有平台）

npm install -g firebase-tools
firebase --version

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

curl -sL firebase.tools | bash

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

# 设置环境变量指向服务账号 JSON 密钥文件
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
firebase deploy --non-interactive

通过技能脚本安装

bash scripts/install.sh

核心用法

身份验证

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

项目管理

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

部署

# 部署所有内容
firebase deploy

# 部署特定目标
firebase deploy --only hosting
firebase deploy --only functions
firebase deploy --only firestore
firebase deploy --only hosting,functions

# 部署子目标
firebase deploy --only functions:myFunction
firebase deploy --only hosting:my-site
firebase deploy --only firestore:rules
firebase deploy --only firestore:indexes

# 排除目标
firebase deploy --except functions

# 附带消息
firebase deploy --message "v2.3.1 发布"

Firebase 模拟器套件

# 启动所有配置的模拟器
firebase emulators:start

# 启动特定模拟器
firebase emulators:start --only auth,firestore,functions

# 带数据导入/导出
firebase emulators:start --import ./emulator-data --export-on-exit

# 针对模拟器运行测试然后关闭
firebase emulators:exec "npm test" --only firestore,auth

# 启用 Functions 调试器（Node.js 检查器，端口 9229）
firebase emulators:start --inspect-functions

本地开发服务器

firebase serve                        # Hosting + HTTPS 函数
firebase serve --only hosting
firebase serve --port 5000

Hosting 命令

# 预览渠道
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

# 多站点管理
firebase hosting:sites:list
firebase hosting:sites:create new-site-id
firebase hosting:disable --site my-old-site

Cloud Functions 命令

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

# 密钥管理（第 2 代 — 取代 functions:config）
firebase functions:secrets:set MY_SECRET
firebase functions:secrets:get MY_SECRET
firebase functions:secrets:prune

# 配置管理（仅第 1 代）
firebase functions:config:set api.key="VALUE"
firebase functions:config:get

Firestore 命令

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

Realtime Database 命令

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 导入/导出

# 导出所有用户
firebase auth:export users.json

# 导入用户（BCRYPT 哈希）
firebase auth:import users.json --hash-algo=BCRYPT

# 导入用户（SCRYPT 哈希 — Firebase 默认）
firebase auth:import users.json \
  --hash-algo=SCRYPT \
  --hash-key=<base64密钥> \
  --salt-separator=<base64分隔符> \
  --rounds=8 \
  --mem-cost=8

Remote Config

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

App Distribution

# 分发 Android APK
firebase appdistribution:distribute app.apk \
  --app APP_ID \
  --release-notes "错误修复和改进" \
  --testers "qa@example.com" \
  --groups "qa-team,beta-users"

# 管理测试人员
firebase appdistribution:testers:add alice@example.com --group-alias qa-team
firebase appdistribution:testers:remove alice@example.com
firebase appdistribution:groups:list

Extensions

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)

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

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

# 为目标名称应用资源
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

# 在部署中使用目标
firebase deploy --only hosting:prod-site

# 清除目标
firebase target:clear hosting prod-site

最佳实践

1. 在 CI/CD 中使用服务账号：设置 GOOGLE_APPLICATION_CREDENTIALS，而不是使用 --token（已弃用）。
2. 在部署中使用 --only：在生产环境中切勿盲目部署所有内容——始终使用 --only 限定范围。
3. 开发时使用模拟器：在部署前始终在本地运行 emulators:start；使用 --import/--export-on-exit 实现数据持久化。
4. 先使用预览渠道再上线：在进行 firebase deploy --only hosting 前，使用 hosting:channel:deploy 进行暂存审查。
5. 优先使用密钥而非 functions:config：对于 Cloud Functions 第 2 代，使用 functions:secrets:set（Secret Manager），而不是已弃用的 functions:config:set。
6. 脚本中添加 --non-interactive：在自动化脚本中始终添加 --non-interactive，避免在提示处挂起。
7. 将 .firebaserc 纳入版本控制：提交 .firebaserc（项目别名），但将密钥和服务账号密钥添加到 .gitignore。
8. 故障排查时使用 --debug：对任何失败的命令添加 --debug 以获取详细输出。

故障排除

参考资料

• Firebase CLI 参考 — 官方完整命令参考
• 完整命令参考 — 所有命令的完整选项和标志
• 安装脚本 — install.sh（设置）· deploy.sh（部署辅助）· emulators.sh（模拟器管理）
• firebase-tools GitHub — 源代码和更新日志
• Firebase CLI 发布说明 — 版本历史
• Auth 导入/导出参考 — 哈希算法详情
• Hosting 预览渠道 — 暂存工作流
• 模拟器套件配置 — 模拟器设置