name: firebase-development-project-setup description: 此技能应用于使用经过验证的架构初始化新的Firebase项目。触发词包括“新建firebase项目”、“初始化firebase”、“firebase init”、“设置firebase”、“创建firebase应用”、“启动firebase项目”。指导CLI设置、架构选择和模拟器配置。

Firebase项目设置

概述

此子技能指导使用经过验证的架构模式初始化新的Firebase项目。它处理Firebase CLI设置、架构决策、模拟器配置和初始项目结构。

核心原则：

所有函数使用TypeScript
从一开始就配置模拟器
早期选择架构模式（托管、认证、函数、安全）
立即设置测试基础设施

适用场景

启动全新的Firebase项目
在代码仓库中首次设置Firebase
用户提及：“新建firebase项目”、“初始化firebase”、“firebase init”、“设置firebase”

不适用于：

为现有项目添加功能 → firebase-development:add-feature
调试现有设置 → firebase-development:debug

架构决策

使用AskUserQuestion预先收集以下四个决策：

1. 托管配置

单站点 - 一个托管站点，简单项目
多站点（site:） - 多个独立的URL
多站点带构建（target:） - 多个站点带有预部署钩子

参考： docs/examples/multi-hosting-setup.md

2. 认证方式

API密钥 - MCP工具、服务器到服务器、程序化访问
Firebase认证 - 带有登录界面的用户端应用
两者 - Web端使用Firebase认证 + 工具使用API密钥

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

3. 函数架构

Express API - 多个相关端点，需要中间件、RESTful路由
领域分组 - 功能丰富的应用，具有不同领域（帖子、管理）
独立文件 - 独立函数，最大模块化

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

4. 安全模型

仅服务器写入（推荐） - 云函数处理所有写入
客户端写入 - 高频率写入，需要最快用户体验，复杂规则

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

TodoWrite工作流

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

步骤1：验证Firebase CLI

firebase --version  # 如果缺失，通过 npm install -g firebase-tools 安装
firebase login

步骤2：创建项目目录

mkdir my-firebase-project && cd my-firebase-project
git init && git branch -m main

创建.gitignore，包含：node_modules/、.env、.env.local、.firebase/、lib/、dist/

步骤3：运行Firebase初始化

firebase init

选择：Firestore、Functions、Hosting、Emulators。为函数选择TypeScript。

步骤4：收集架构决策

使用AskUserQuestion收集上述四个决策。

步骤5：配置firebase.json

根据托管决策进行设置。关键的模拟器设置：

{
  "emulators": {
    "singleProjectMode": true,
    "ui": { "enabled": true, "port": 4000 }
  }
}

参考： docs/examples/multi-hosting-setup.md

步骤6：设置函数结构

根据架构选择：

Express： 创建middleware/、tools/、services/、shared/ 领域分组： 创建shared/types/、shared/validators/ 独立： 创建functions/

安装依赖：express、cors、firebase-admin、firebase-functions、vitest、biome

步骤7：创建初始函数代码

创建functions/src/index.ts并包含ABOUTME注释。对于Express模式，包含健康检查端点。

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

步骤8：配置Firestore规则

根据安全模型决策。始终包含：

辅助函数（isAuthenticated()、isOwner()）
底部的默认拒绝规则

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

步骤9：设置测试

创建vitest.config.ts和vitest.emulator.config.ts。设置__tests__/和__tests__/emulator/目录。

步骤10：配置Biome

创建包含推荐规则的biome.json。运行npm run lint:fix。

步骤11：设置环境变量

创建.env.example模板。复制到.env并填写值。

对于托管：创建hosting/.env.local，包含NEXT_PUBLIC_USE_EMULATORS=true。

步骤12：初始Git提交

git add . && git commit -m "feat: 初始Firebase项目设置"

步骤13：启动模拟器

firebase emulators:start
open http://127.0.0.1:4000

验证所有服务启动。如果使用Express，测试健康端点。

步骤14：创建初始测试

创建functions/src/__tests__/setup.test.ts进行基本验证。运行npm test。

验证清单

完成前检查：

[ ] Firebase CLI已安装并登录
[ ] TypeScript函数编译：npm run build
[ ] 所有测试通过：npm test
[ ] 代码检查通过：npm run lint
[ ] 模拟器启动无错误
[ ] 模拟器UI可通过http://127.0.0.1:4000访问
[ ] Git已初始化并提交
[ ] .env文件已创建并git忽略
[ ] 所有文件都有ABOUTME注释
[ ] 架构决策已记录

项目结构

Express API：

functions/src/
├── index.ts
├── middleware/apiKeyGuard.ts
├── tools/
├── services/
└── __tests__/

领域分组：

functions/src/
├── index.ts
├── posts.ts
├── users.ts
├── shared/types/
└── __tests__/

独立文件：

functions/
├── functions/upload.ts
├── functions/process.ts
└── index.js

后续步骤

设置完成后：

添加第一个功能 → firebase-development:add-feature
审查设置 → firebase-development:validate
调试问题 → firebase-development:debug

模式参考

托管： docs/examples/multi-hosting-setup.md
认证： docs/examples/api-key-authentication.md
函数： docs/examples/express-function-architecture.md
规则： docs/examples/firestore-rules-patterns.md
模拟器： docs/examples/emulator-workflow.md