AngularFire 安装与项目初始化指南：从 `ng add @angular/fire` 到 Firestore 数据流绑定

• 后端

导读

本文基于 AngularFire 官方 Quickstart 文档（docs/install-and-setup.md）编写，完整讲解在全新 Angular 项目中接入 AngularFire 的六个步骤：创建项目、运行ng add @angular/fire、注入Firestore、把集合绑定为响应式列表、本地联调、部署上线。你将掌握ng add背后的 schematics 究竟改动了哪些文件、provideFirebaseApp/provideFirestore等 provider 的底层机制，以及如何用collectionData让 Firestore 数据实时流入 Angular 模板。文中所有实现细节均有仓库源码佐证，可直接对照src/schematics/与src/firestore/目录深入研读。

开始之前：三条前置检查

Quickstart 在正式动手前给出了三条容易踩坑的注意事项，它们直接决定了ng add能否一次成功：

1. Firebase CLI 版本 ≥ 14。整个初始化流程由 Firebase CLI（firebase-tools）驱动。ng add在你机器上没有 CLI 时会自动安装并引导你登录，但不会升级已存在的旧版本。如果本机已有旧版 CLI，setup 会以firebase-tools version 14.0.0+ is required, please upgrade and run again终止。提前处理或清除该错误的方法是：

   npm install -g firebase-tools firebase login

   从源码看，setup 阶段会通过 firebaseTools.ts 调用 CLI 的login、projects.list、apps.sdkconfig等能力，旧版本缺少这些 API 就无法完成交互式初始化。

2. 新版 Angular 主版本请使用@next。AngularFire 默认发布渠道（latest）与最新 Angular 大版本之间可能存在 peer-dependency 冲突。若ng add @angular/fire报 Angular peer 依赖冲突，说明你的 Angular 比 AngularFire 默认版本更新，此时应安装与之匹配的预发布版本：

   ng add @angular/fire@next

   仓库的 common.ts 还揭示了一个细节：当安装的是预发布版本时，schematics 会把package.json中的@angular/fire声明钉死（pin）到精确版本，因为类似^21.0.0-rc.0的预发布区间也会匹配每次 merge 到 main 后发布的 canary 构建，后续安装可能静默替换掉你精心选择的版本。

3. 无害的 CLI 噪音。初始化期间 Firebase CLI 可能打印punycode弃用警告，或询问是否启用额外功能（例如 Gemini）。这些来自 CLI 本身，与 AngularFire 无关，忽略即可。

第一步：创建 Angular 项目

Quickstart 提供了两种等价方式，以及一种可选的直接安装 CLI 方式：

# 方式一：yarn create yarn create @angular <project-name> cd <project-name>

# 方式二：npm create npm create @angular <project-name> cd <project-name>

# 方式三（可选）：直接安装工具链 npm install -g @angular/cli ng new <project-name> cd <project-name>

Angular CLI 的new命令会以最新版 Angular 构建一个全新的项目结构。创建过程中 CLI 会询问是否启用SSR（服务端渲染），这个选择会直接影响第六步的部署方式，值得提前留意。

第二步：运行ng add @angular/fire

在项目根目录执行：

ng add @angular/fire

这是整个接入流程的核心。ng add会安装 AngularFire 并自动完成项目配置，具体做两件事：

1. 交互式提问：提示你勾选要启用的功能模块、选择要使用的 Firebase 项目（必要时会引导你登录 Firebase 账号）。
2. 改写应用配置：向应用配置（如app.config.ts）中注入provideFirebaseApp(...)以及每个勾选功能对应的 provider，并把你的 Firebase 配置内联进去——不会创建 environment 文件。

ng add底层到底改了什么

理解ng add的行为，最好的方式是直接看它背后的 schematics 源码，入口在 src/schematics/add/index.ts：

• 首先addDependencies按peerDependencies把依赖写入package.json（src/schematics/common.ts）；
• 接着alignFirebaseVersion会把工作区里的firebase依赖对齐到^12.18.0这个范围（见 common.ts）。注释里给出了原因：AngularFire 自带一份firebase依赖，如果你的工作区钉在更老的 major 版本，npm 会静默地在@angular/fire下嵌套出第二份 SDK 副本，运行时两份副本会互相拒绝对方的对象（对应 issue #3684、#3681、#3682）；
• 然后pinInstalledPrereleaseVersion处理上文提到的预发布版本钉死问题；
• 最后调度一个ng-add-setup-projectschematic 完成后续的交互式设置（src/schematics/setup/index.ts）。

setup 阶段（setup/index.ts）的交互逻辑非常完整：

• 通过 checkbox 多选询问"What features would you like to setup?"，可选功能在 src/schematics/interfaces.ts 中定义，共 12 项：Authentication、Google Analytics、App Check、Firestore、Realtime Database、Data Connect、Cloud Functions (callable)、Cloud Messaging、Performance Monitoring、Cloud Storage、Remote Config、AI Logic；
• 询问使用哪个 Firebase 账号（setup/prompts.ts）；
• 通过模糊搜索（autocomplete）选择或新建 Firebase 项目（projectPrompt），甚至允许直接在向导里输入 project id 创建新项目；
• 选择或新建 Web 应用（appPrompt），然后调用firebaseTools.apps.sdkconfig('web', ...)拉取 SDK 配置，再从中筛出initializeApp()能接受的键（apiKey、authDomain、databaseURL、projectId、storageBucket、messagingSenderId、appId、measurementId、recaptchaSiteKey，见 setup/index.ts）；
• 把选中的 Firebase 项目写入.firebaserc的projects.default（setup/firebaseConfigs.ts），这样后续firebase命令无需再交互式选择项目；
• 如果勾选了 Firestore，会自动生成测试模式（test mode）的firestore.rules（30 天后过期）与空的firestore.indexes.json，并在firebase.json中注册firestore段（setup/firebaseConfigs.ts）；
• 如果勾选了 Data Connect，还会调用firebaseTools.init("dataconnect")初始化本地配置并解析 connector SDK 生成情况。

生成的 provider 是如何工作的

ng add向应用配置注入的provideFirebaseApp实现在 src/app/app.module.ts。它的要点是：

• 通过makeEnvironmentProviders注册一个PROVIDED_FIREBASE_APPS多值 provider，用工厂firebaseAppFactory在NgZone 之外（zone.runOutsideAngular）执行fn(injector)调用initializeApp(config)——这是 AngularFire 避免 Firebase 回调频繁触发变更检测的关键设计；
• 同时调用registerVersion('angularfire', VERSION.full, 'app')向 Firebase SDK 登记 AngularFire 版本，用于问题诊断；
• FirebaseApp的默认注入解析逻辑在defaultFirebaseAppFactory：如果只显式提供了单个 app 就返回它，否则回退到 Firebase SDK 的默认 app（getApp()）。

类似地，provideFirestore在 src/firestore/firestore.module.ts 中注册Firestore实例，同样在 zone 外构造，并且依赖顺序上让 Auth 与 AppCheck 先于 Firestore 加载（源码注释明确写着 "Firestore+Auth work better if Auth is loaded first"）。

第三步：注入Firestore

打开/src/app/app.ts，进行如下修改：

import { Component, inject } from '@angular/core'; import { AsyncPipe } from '@angular/common'; import { Firestore } from '@angular/fire/firestore'; @Component({ selector: 'app-root', templateUrl: './app.html', styleUrl: './app.css', imports: [AsyncPipe], }) export class App { firestore: Firestore = inject(Firestore); constructor() { } }

Firestore类型本身定义在 src/firestore/firestore.ts：它是一个接口与类的同构声明，类构造器直接把底层 Firebase Firestore 实例原样返回，因此你注入的Firestore本质上就是 Firebase JS SDK 的 Firestore 实例，只是被 AngularFire 的 DI 体系管理起来。借助 Angular 的inject()函数，组件无需构造函数参数即可拿到实例。

第四步：把 Firestore 集合绑定为响应式列表

继续修改/src/app/app.ts：

import { Component, inject } from '@angular/core'; import { AsyncPipe } from '@angular/common'; import { Observable } from 'rxjs'; import { Firestore, collection, collectionData } from '@angular/fire/firestore'; interface Item { name: string; } @Component({ selector: 'app-root', imports: [AsyncPipe], templateUrl: './app.html', styleUrl: './app.css' }) export class App { firestore: Firestore = inject(Firestore); items$: Observable<Item[]>; constructor() { const aCollection = collection(this.firestore, 'items') this.items$ = collectionData<Item>(aCollection); } }

再打开/src/app/app.html：

<ul> @for (item of items$ | async; track item) { <li>{{ item.name }}</li> } </ul>

这里的核心是RxJS Observable + AsyncPipe的数据流组合：

• collection(this.firestore, 'items')创建指向items集合的引用；
• collectionData<Item>(aCollection)把该集合转换为一个发出Item[]数组的 Observable。它在 src/firestore/rxfire.ts 中通过ɵzoneWrap对 rxfire 的collectionData做了 zone 包装，确保数据回调在 Angular zone 内触发变更检测；
• 模板中的items$ | async自动订阅并渲染数组，@for块遍历每一项输出item.name。

从模块结构看，@angular/fire/firestore的公开 API（public_api.ts）同时导出 AngularFire 的provideFirestore/Firestore以及 Firebase JS SDK 的全部函数（collection、doc、where等，见 src/firestore/firebase.ts），因此你可以在 Angular 组件里直接使用熟悉的 Firebase 函数式 API。

第五步：本地运行

ng serve

Angular 应用编译并在本地提供服务后，浏览器里应看到一个空列表——因为此时items集合还没有数据。

在另一个终端标签页中，按照 Firebase 官方文档往items集合添加数据即可。需要特别强调的是：由于此时还没有接入用户认证，请务必将 Firestore 以**测试模式（test mode）**启动，或在安全规则中允许读取items集合（allow read: if true），否则数据读取会被规则拦截。

一旦你创建了items集合并开始插入文档，就会看到数据实时流入 Angular 应用并渲染在浏览器中——这正是collectionData订阅 onSnapshot 实时监听带来的效果。

测试模式规则提醒

如果你是用ng add勾选 Firestore 完成初始化的，schematics 生成的 firestore.rules 本身就是测试模式：允许任何人读写，但30 天后过期，之后所有客户端请求都会被拒绝（setup/firebaseConfigs.ts）。因此上线前务必把安全规则替换为正式的鉴权规则。

第六步：部署应用

部署方式取决于应用是否使用了 SSR（服务端渲染）——Angular CLI 创建项目时会询问这一项。

纯客户端渲染应用（默认）：构建产物是静态文件，部署到 Firebase Hosting。请按 Firebase 官方 Hosting quickstart 构建并部署应用，也可以使用本仓库提供的部署 builder（@angular/fire的 schematics 中内置了 deploy 支持，见 src/schematics/deploy/builder.ts）。

SSR 应用：运行的是 Node 服务器，因此建议部署到Firebase App Hosting——这也是 Firebase 对 SSR 场景推荐的路径。完整的部署步骤见 Firebase App Hosting 指南，该指南还覆盖了一个常见坑：SSR 应用部署后静默回退到客户端渲染（例如服务器端数据获取失败、Node 运行环境缺失等导致），需要按指南逐一排查。

仓库的示例应用 sample/src/app/app.config.ts 展示了生产级配置的形态：provideZonelessChangeDetection()、provideClientHydration(withIncrementalHydration())与provideAuth(...)组合使用，并演示了如何在 provider 工厂里判断_canInitEmulator后连接 Auth 模拟器——可作为你初始化完成后进一步接入各模块的参考模板。

常见问题速查

小结

从yarn create @angular到ng add @angular/fire，再到inject(Firestore)与collectionData的响应式绑定，整个过程被 AngularFire 的 schematics 高度自动化：它不仅写好了 provider，还会同步管理firebase.json、.firebaserc、firestore.rules等配套文件。理解 src/schematics/add/index.ts 与 src/schematics/setup/index.ts 的实现，能让你在遇到版本对齐、规则过期、双 SDK 副本等边缘问题时快速定位根因。后续深入某个模块（Auth、Storage、Functions 等）时，各模块目录下的*.module.ts与rxfire.ts都遵循与 Firestore 相同的 provider + zone 包装模式，可以举一反三。

• 后端