ionic-firebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Firebase (Auth + Firestore)

The default backend for most Ionic apps. Auth handles sign-up / sign-in (including social providers); Firestore handles persistent data with realtime sync and offline support.

大多数Ionic应用的默认后端方案。Auth负责注册/登录（包括第三方社交提供商）；Firestore负责数据持久化，支持实时同步和离线功能。

When to consult

适用场景参考

Project setup + native config files (
```
google-services.json
```
,
```
GoogleService-Info.plist
```
): setup.md
Auth (email, Google, Apple, magic link): auth.md
Firestore (read/write/realtime/offline): firestore.md
Per-framework integration snippets: framework-snippets.md

项目设置 + 原生配置文件 (
```
google-services.json
```
,
```
GoogleService-Info.plist
```
)：setup.md
Auth（邮箱、Google、Apple、魔术链接）：auth.md
Firestore（读/写/实时/离线）：firestore.md
各框架集成代码片段：framework-snippets.md

Library choice

库选择

Two viable approaches:

Approach	When to pick
Firebase JS SDK ( `firebase` npm package)	Web-first, simple cases, web/mobile parity. Works in browser, iOS WKWebView, Android WebView. Auth popups can be tricky on native.
Capacitor Firebase plugins ( `@capacitor-firebase/*` )	Native auth dialogs (Google sign-in via native sheets), offline Firestore via native SDKs, push via native FCM. More setup, much better UX.

Recommendation: use the JS SDK for v1 (faster), migrate to

@capacitor-firebase/*

plugins when you hit native UX gaps (especially Google Sign-In, which is rough via web-only on Android).

This skill covers both — pick whichever fits.

有两种可行方案：

方案	适用场景
Firebase JS SDK ( `firebase` npm包)	优先Web端，简单场景，Web/移动端一致性。适用于浏览器、iOS WKWebView、Android WebView。原生端的Auth弹窗可能存在问题。
Capacitor Firebase插件 ( `@capacitor-firebase/*` )	原生Auth对话框（通过原生面板实现Google登录），通过原生SDK实现Firestore离线功能，原生FCM推送。设置步骤更多，但用户体验更佳。

推荐方案：v1版本使用JS SDK（更快上手），当遇到原生用户体验瓶颈时（尤其是Android端的Google登录，纯Web方案体验较差），迁移至

@capacitor-firebase/*

插件。

本技能涵盖两种方案——可根据需求选择。

Hard rules

硬性规则

✅ Never put Firebase Admin SDK code in the app. That's server-only — uses a service account with full permissions.
✅ Firebase web config (
```
apiKey
```
,
```
projectId
```
, etc.) is safe to ship — Security Rules do the gating. See
```
../ionic-shared/references/environments-and-keys.md
```
.
✅ Write Firestore Security Rules before going live. The default "test mode" rules expire after 30 days and become "deny all" if not replaced.
❌ Don't use Realtime Database for new projects unless you have a specific reason — Firestore is the modern choice.
❌ Don't query a collection with no index expecting it to scale — Firestore's query patterns require composite indexes for compound filters.

✅ 切勿在应用中加入Firebase Admin SDK代码。这仅适用于服务器端——它使用拥有全部权限的服务账户。
✅ Firebase Web配置 (
```
apiKey
```
,
```
projectId
```
等) 可以安全地随应用发布——权限控制由安全规则实现。详见
```
../ionic-shared/references/environments-and-keys.md
```
。
✅ 在上线前编写Firestore安全规则。默认的“测试模式”规则会在30天后过期，若未替换则会变为“拒绝所有请求”。
❌ 除非有特殊需求，否则新项目不要使用Realtime Database——Firestore是更现代的选择。
❌ 不要在没有索引的情况下查询集合并期望其能扩展——Firestore的查询模式需要复合索引来支持复合筛选器。

Library

安装命令

bash

npm install firebase

bash

npm install firebase

OR for native plugins:

npm install @capacitor-firebase/app @capacitor-firebase/authentication @capacitor-firebase/firestore npx cap sync

undefined

npm install @capacitor-firebase/app @capacitor-firebase/authentication @capacitor-firebase/firestore npx cap sync

undefined

Pairs with

配套功能

Push notifications via FCM: Firebase's
```
google-services.json
```
/
```
GoogleService-Info.plist
```
also covers FCM. Wire push handling itself via
```
../ionic-shared/references/push-notifications.md
```
— the plugin (
```
@capacitor/push-notifications
```
) is independent of Firebase Auth/Firestore but uses the same native config files.
Magic-link sign-in: requires Universal Link / App Link plumbing — see
```
../ionic-deep-links/
```
. Firebase Dynamic Links is shut down — your own deep-link infra is the path.
Sign in with Apple: integrates via
```
@capacitor-firebase/authentication
```
(this skill, auth.md). Don't also install
```
@capacitor-community/apple-sign-in
```
— see
```
../ionic-apple-sign-in/SKILL.md
```
for when to use the standalone plugin instead.

通过FCM实现推送通知：Firebase的
```
google-services.json
```
/
```
GoogleService-Info.plist
```
也适用于FCM。推送处理的集成可参考
```
../ionic-shared/references/push-notifications.md
```
——对应的插件（
```
@capacitor/push-notifications
```
）独立于Firebase Auth/Firestore，但使用相同的原生配置文件。
魔术链接登录：需要配置Universal Link / App Link——详见
```
../ionic-deep-links/
```
。Firebase Dynamic Links已停止服务——需自行搭建深度链接基础设施。
Apple登录：通过
```
@capacitor-firebase/authentication
```
集成（本技能，auth.md）。请勿同时安装
```
@capacitor-community/apple-sign-in
```
——如需使用独立插件，请参考
```
../ionic-apple-sign-in/SKILL.md
```
。