⚡

Firebase开发调试Skill firebase-development-debug

Firebase 开发调试技能是一个系统性的故障排除指南，专门用于解决 Firebase 后端开发过程中的常见问题。它涵盖了 Firebase 模拟器启动失败、Firestore 安全规则违规、云函数执行错误、身份验证配置问题以及项目部署失败等核心场景。该技能提供了一套结构化的排查步骤，包括问题识别、日志分析、模拟器UI诊断、规则测试、调试日志添加和配置验证。关键词包括：Firebase 调试、模拟器故障排除、Firestore 规则错误、云函数部署、权限被拒绝、后端开发问题解决。

Serverless 0 次安装 0 次浏览 更新于 2/28/2026

名称: firebase-development-debug 描述: 此技能应在排查Firebase模拟器问题、规则违规、函数错误、身份验证问题或部署失败时使用。触发关键词包括“错误”、“无法工作”、“调试”、“故障排除”、“失败”、“损坏”、“权限被拒绝”、“模拟器问题”。

Firebase 调试

概述

此子技能指导系统性地排查Firebase开发问题。它处理模拟器问题、规则违规、函数错误、身份验证问题和部署失败。

关键原则：

  • 首先确定问题类型（模拟器、规则、函数、身份验证、部署）
  • 使用模拟器UI和规则游乐场进行诊断
  • 在重启前导出模拟器状态
  • 记录问题和解决方案以供将来参考

适用场景

  • 模拟器无法启动或存在端口冲突
  • 遇到Firestore规则违规（PERMISSION_DENIED）
  • 云函数返回错误或未执行
  • 模拟器中的身份验证不工作
  • 部署失败并出现隐晦错误
  • 用户提及：“调试”、“故障排除”、“错误”、“无法工作”、“失败”

不适用于：

  • 设置新项目 → firebase-development:project-setup
  • 添加新功能 → firebase-development:add-feature
  • 没有特定错误的代码审查 → firebase-development:validate

TodoWrite 工作流

创建包含以下10个步骤的清单：

步骤 1: 识别问题类型

对错误进行分类：

类别 症状 关键词
模拟器无法启动 端口冲突、初始化错误 “EADDRINUSE”、“模拟器失败”
规则违规 读/写时权限被拒绝 “PERMISSION_DENIED”、“权限不足”
函数错误 HTTP 500、超时、未执行 “函数失败”、“超时”
身份验证问题 令牌错误、未认证 “身份验证失败”、“无效令牌”
部署失败 部署命令失败 “部署失败”、“部署错误”

如果不明确，使用 AskUserQuestion 来澄清问题类型。

步骤 2: 检查模拟器日志和终端

对于正在运行的模拟器： 在重现问题时观察终端输出。

对于无法启动的模拟器：

lsof -i :4000 && lsof -i :5001 && lsof -i :8080  # 检查端口
kill -9 <PID>  # 终止冲突进程

对于部署错误： 检查 firebase-debug.log

参考： docs/examples/emulator-workflow.md

步骤 3: 打开模拟器 UI

open http://127.0.0.1:4000

使用模拟器 UI 来：

  • 查看 Firestore 数据和结构
  • 检查已认证用户
  • 查看函数调用日志
  • 搜索合并日志

步骤 4: 在游乐场测试规则（如果是规则问题）

在模拟器 UI → Firestore → 规则游乐场：

  1. 选择操作类型（获取/列表/创建/更新/删除）
  2. 指定文档路径
  3. 设置身份验证上下文（uid、自定义声明）
  4. 为写入操作添加请求数据
  5. 运行模拟并查看评估跟踪

参考： docs/examples/firestore-rules-patterns.md

步骤 5: 添加调试日志（如果是函数错误）

添加策略性的 console.log 语句：

  • 函数入口确认
  • 输入数据（req.body、req.params）
  • 身份验证上下文（userId、API 密钥）
  • 中间操作结果
  • 带有堆栈跟踪的错误详情

在重现问题时观察终端输出。

参考： docs/examples/express-function-architecture.md

步骤 6: 验证身份验证配置（如果是身份验证问题）

检查环境变量：

cat functions/.env
cat hosting/.env.local  # 应包含 NEXT_PUBLIC_USE_EMULATORS=true

检查客户端代码和 API 密钥中间件中的模拟器连接。

参考： docs/examples/api-key-authentication.md

步骤 7: 检查部署配置（如果是部署失败）

cat firebase-debug.log  # 完整错误详情
cat firebase.json       # 配置问题
cat .firebaserc         # 项目 ID
firebase target:list    # 验证目标

在本地测试预部署钩子：

cd functions && npm run build

步骤 8: 导出模拟器状态

在进行修复之前：

# 优雅关闭（Ctrl+C 会自动导出）
# 或手动导出：
firebase emulators:export ./backup-data

验证导出：ls -la .firebase/emulator-data/

步骤 9: 实施并测试修复

根据诊断应用修复，然后：

firebase emulators:start --import=.firebase/emulator-data

验证：

  • 原始错误不再发生
  • 终端显示成功日志
  • 模拟器 UI 确认预期行为

步骤 10: 记录问题和解决方案

在 docs/debugging-notes.md 中创建条目：

  • 症状和确切错误信息
  • 根本原因
  • 应用的解决方案
  • 未来预防措施

常见问题快速参考

问题 解决方案
端口冲突 lsof -i :<端口>，终止进程
数据持久性丢失 使用 Ctrl+C（而非 kill）停止模拟器
冷启动延迟 首次调用需要 5-10 秒（正常）
规则未重新加载 重启模拟器
Admin 与 Client SDK Admin 绕过规则，Client 遵守规则
缺少 CORS 添加 app.use(cors({ origin: true }))
模拟器连接 设置 NEXT_PUBLIC_USE_EMULATORS=true
API 密钥前缀 验证前缀与实际密钥匹配

与超级能力的集成

如果 Firebase 特定工具未揭示根本原因，请调用 superpowers:systematic-debugging 来处理：

  • 复杂的多服务交互
  • 竞态条件或时序问题
  • 超出 Firebase 层的调用堆栈跟踪

模式参考

  • 模拟器工作流： docs/examples/emulator-workflow.md
  • 规则模式： docs/examples/firestore-rules-patterns.md
  • 身份验证模式： docs/examples/api-key-authentication.md
  • 函数： docs/examples/express-function-architecture.md