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. 安全模型

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

参考： 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: initial Firebase project setup"

步骤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