firebase-cli

firebase-cli — Firebase 平台运维

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

当工作的核心是通过 CLI 运维 Firebase 平台／项目时，使用此技能。

何时使用此技能

• 安装或更新 firebase-tools，选择身份验证方式，并确认 CLI 能够操作目标项目
• 使用 firebase init、.firebaserc、别名、目标和部署范围，在仓库中初始化 Firebase 配置
• 运行 Firebase Emulator Suite，以进行本地开发、持久化和测试
• 通过 CLI 部署或提升 Hosting、Functions、规则、Remote Config、Extensions 或 App Hosting
• 管理预览通道、项目别名、选择性部署，以及 Firebase 运维的 CI/CD 身份验证
• 执行 Firebase 管理／数据任务，例如身份验证导入／导出、App Distribution、Remote Config 回滚和扩展管理

何时不使用此技能

• 主要工作是在 Firebase／Google AI 产品中编排后端 AI 工作流、工具、流程、RAG、评估或可观测性 → 使用 genkit
• 主要工作是为 Gemini 驱动的应用内功能直接集成应用／客户端 SDK → 使用 genkit（client-ai-logic 模式）
• 主要工作是选择身份验证技术栈和设计产品身份验证架构，而非执行 Firebase CLI 操作 → 使用 authentication-setup
• 主要工作是设计架构／索引，而非执行 Firebase CLI 命令 → 使用 database-schema-design
• 主要工作是制定跨供应商的通用发布策略，而非执行 Firebase 专属运维命令 → 使用 deployment-automation

说明

步骤 1：选择操作模式

首先，将请求归入以下某种模式：

模式	适用情况	主要支持内容
安装／身份验证	CLI 缺失、版本过旧或凭据受阻	scripts/install.sh、references/install-auth-and-bootstrap.md
初始化／配置	需要 firebase init、别名、目标或仓库配置布局	references/install-auth-and-bootstrap.md
本地模拟器	需要本地 Firebase 运行时、持久化或测试框架	scripts/emulators.sh、references/emulator-and-release-workflows.md
部署／发布	需要限定范围的部署、预览通道、App Hosting 发布或 CI 执行	scripts/deploy.sh、references/emulator-and-release-workflows.md
管理／数据运维	需要身份验证导入／导出、Remote Config、App Distribution、Extensions 或 Data Connect 命令	references/admin-and-data-operations.md
不确定／混合任务	需要协助判断工作属于 Firebase CLI 还是相邻领域	references/modes-and-routing.md

步骤 2：在进行任何更改前确认先决条件

1. 确认 CLI 已安装并记录版本：firebase --version
2. 确认运行时满足当前 firebase-tools 版本的要求：
   • 通过 npm 安装需要 Node.js 20+
   • 独立安装程序仅支持 macOS/Linux
3. 检查身份验证方式：
   • 本地交互式操作 → firebase login
   • CI／非交互式操作 → 通过 GOOGLE_APPLICATION_CREDENTIALS 使用服务账号凭据
4. 部署或运行模拟器前检查项目配置：
   • firebase.json
   • .firebaserc
   • 任何特定目标目录（functions/、Hosting 输出目录、规则／索引文件）

步骤 3：运行能够满足请求的最精简工作流

模式 A — 安装／身份验证

• 通过 bash scripts/install.sh 安装或更新
• 若有 Node.js 20+，优先使用 npm 安装：npm install -g firebase-tools
• 在本地使用浏览器 OAuth：firebase login
• 在 CI 中优先使用服务账号凭据，而非已弃用的 --token／FIREBASE_TOKEN

模式 B — 初始化 / 配置

• 使用 firebase init 初始化所需的具体功能，不要不加区分地启用所有功能
• 使用 firebase use 和 firebase use --add 设置 / 检查别名
• 当存在多个 Hosting 站点、数据库实例或存储桶时，使用部署目标
• 记录哪些 Firebase 功能属于此仓库，哪些属于相邻技能

模式 C — 本地模拟器

• 使用 bash scripts/emulators.sh --persistent 持久保存本地数据
• 使用 firebase emulators:exec "<test command>" 运行一次性测试
• 使用 --only auth,firestore,functions 仅启动所需的模拟器
• 在仓库中明确模拟器配置和种子数据要求

模式 D — 部署 / 发布

• 使用 --only 或 --except 限定部署范围
• 在部署到生产环境之前，优先使用预览渠道审查 Hosting 更改
• 对于 App Hosting，应将后端创建 / 推出视为运维工作流，而不是通用 Web 部署捷径
• 在 CI 中使用 --non-interactive 和明确的凭据
• 部署后验证具体更改，不要仅凭命令退出状态就认定成功

模式 E — 管理 / 数据运维

• 使用 CLI 执行身份验证导入 / 导出、Remote Config 版本管理 / 回滚、App Distribution、Extensions 和定向清理任务
• 对 firestore:delete --recursive --force 等破坏性命令务必明确说明
• 对大型 / 对导入敏感的任务，在执行前记录准确的哈希值 / 配置 / 版本参数

第 4 步：工作性质发生变化时，积极转交

将 firebase-cli 作为运维入口，但如果实际工作内容属于以下范围，则应转交：

• 应用 / 客户端 Gemini SDK 功能接入 → genkit（client-ai-logic 模式）
• 流程 / 工具 / RAG / 评估编排 → genkit
• 身份验证模型的产品决策 → authentication-setup
• 架构 / 索引建模 → database-schema-design
• 与提供商无关的发布策略 → deployment-automation

第 5 步：验证结果

对于每种模式，都应验证最小且真实的产物：

• 安装 / 身份验证 → firebase --version、firebase login:list，或成功执行需要身份验证的命令
• 初始化 / 配置 → firebase.json、.firebaserc、目标映射
• 模拟器 → 正在运行的端口、导入 / 导出的数据目录、成功运行的测试
• 部署 / 发布 → 已部署目标列表、预览 URL，或部署后的冒烟测试
• 管理 / 数据运维 → 导出 / 导入的文件、版本回滚确认、测试人员 / 群组更新，或扩展程序状态

示例

示例 1：规范地初始化 Firebase 仓库

Prompt: "Set up Firebase in this repo for Hosting + Functions + preview channels"

Mode:
- Bootstrap / config

Likely actions:
- bash scripts/install.sh
- firebase login
- firebase init hosting functions
- firebase use --add
- firebase target:apply ...   # if multi-site is needed

示例 2：支持持久化的本地模拟器工作流

Prompt: "Run auth + firestore emulators locally and keep the data between runs"

Mode:
- Local emulators

Likely actions:
- bash scripts/emulators.sh --only auth,firestore --persistent
- or firebase emulators:start --only auth,firestore --import ./emulator-data --export-on-exit

示例 3：Firebase 发布 / 预览流程

Prompt: "Deploy Hosting to a reviewable staging channel, then ship production after approval"

Mode:
- Deploy / release

Likely actions:
- bash scripts/deploy.sh --channel staging --expires 7d
- firebase hosting:channel:open staging
- firebase deploy --only hosting

示例 4：将 AI 工作流相关工作转交给其他技能

Prompt: "Build a Firebase RAG flow with tools, evals, and observability"

Decision:
- Route to `genkit`
- Keep `firebase-cli` only for operator tasks like local setup or deploy wiring if needed

最佳实践

1. 优先选择工作流，而不是罗列命令 — 先选择模式，再选择命令
2. 在 CI 中使用服务账号 — 将 --token / FIREBASE_TOKEN 视为已弃用的备用方案，而非默认方式
3. 严格限定部署范围 — --only 和预览渠道可以缩小意外影响范围
4. 明确仓库配置 — firebase.json、.firebaserc 和目标映射应与仓库实际的部署范围一致
5. 有目的地在模拟器工作中使用持久化 — 导入 / 导出目录可以让本地调试和测试重复进行
6. 将 Firebase 运维工作与应用 / AI 逻辑工作分开 — 当 CLI 不再是主要工作时，转交给 genkit（client-ai-logic 模式）或 genkit
7. 将破坏性管理命令视为高风险操作 — 在执行删除 / 回滚 / 导入操作前，确认路径、版本和资源 ID

参考资料

• 模式选择与路由分流
• 安装、身份验证与引导指南
• 模拟器与发布工作流
• 管理与数据操作
• 完整命令参考
• 脚本 — install.sh、deploy.sh、emulators.sh
• Firebase CLI 参考
• firebase-tools GitHub 仓库