⚡

Firebase开发调试Skill firebase-development-debug

Firebase开发调试技能是用于系统性地诊断和解决Firebase后端开发过程中常见问题的指南。它专注于排查Firebase模拟器启动失败、Firestore安全规则违规、云函数执行错误、用户认证故障以及项目部署失败等核心问题。该技能提供了一套结构化的10步工作流，包括问题分类、日志检查、模拟器UI诊断、规则测试、调试日志添加、配置验证和状态管理等关键步骤。适用于开发者在本地开发、测试和部署Firebase应用时，快速定位和修复后端服务相关的错误和异常。关键词：Firebase调试，模拟器问题，Firestore规则，云函数错误，认证故障，部署失败，后端开发调试。

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

name: firebase-development-debug description: 此技能应用于排查Firebase模拟器问题、规则违规、函数错误、认证问题或部署失败时。触发关键词包括“error”、“not working”、“debug”、“troubleshoot”、“failing”、“broken”、“permission denied”、“emulator issue”。

Firebase 调试

概述

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

关键原则：

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

适用场景

  • 模拟器无法启动或存在端口冲突
  • 遇到Firestore规则违规（PERMISSION_DENIED）
  • 云函数返回错误或未执行
  • 模拟器中认证不工作
  • 部署失败并出现隐晦错误
  • 用户提及：“debug”、“troubleshoot”、“error”、“not working”、“failing”

不适用于：

  • 设置新项目 → firebase-development:project-setup
  • 添加新功能 → firebase-development:add-feature
  • 无具体错误的代码审查 → firebase-development:validate

TodoWrite 工作流

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

步骤1：识别问题类型

对错误进行分类：

类别 症状 关键词
模拟器无法启动 端口冲突、初始化错误 “EADDRINUSE”、“emulator failed”
规则违规 读写权限被拒绝 “PERMISSION_DENIED”、“insufficient”
函数错误 HTTP 500、超时、未执行 “function failed”、“timeout”
认证问题 令牌错误、未认证 “auth failed”、“invalid token”
部署失败 部署命令失败 “deployment failed”、“deploy error”

如果不明确，使用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. 选择操作类型（get/list/create/update/delete）
  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