flutter-firebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Firebase Setup

Firebase配置

Use

firebase_core

for initialization — call

Firebase.initializeApp()

before

runApp()

Use
```
flutterfire configure
```
for platform-specific setup
Use separate Firebase projects per flavor (see
```
app-config
```
skill)
Register Firebase services via
```
injectable
```
for consistent DI

使用
```
firebase_core
```
完成初始化 —— 在调用
```
runApp()
```
之前先执行
```
Firebase.initializeApp()
```
使用
```
flutterfire configure
```
完成平台专属配置
不同环境版本对应独立的Firebase项目（参考
```
app-config
```
技能）
通过
```
injectable
```
注册Firebase服务，实现统一的依赖注入

Authentication

身份验证

Use
```
firebase_auth
```
for user management
Wrap all auth calls in an
```
AuthRepository
```
— no direct
```
FirebaseAuth
```
usage in BLoCs or UI
Support email/password, Google Sign-In, and Apple Sign-In at minimum

Handle auth state changes via

FirebaseAuth.instance.authStateChanges()

stream in

AuthBloc

Store auth tokens via
```
flutter_secure_storage
```
— never in
```
SharedPreferences
```
or source code
Implement proper sign-out: clear local cache, navigate to login, dispose user-specific BLoCs

使用
```
firebase_auth
```
实现用户管理
所有认证相关调用都封装在
```
AuthRepository
```
中 —— 禁止在BLoCs或UI层直接调用
```
FirebaseAuth
```
至少支持邮箱/密码、Google Sign-In、Apple Sign-In三种认证方式

在

AuthBloc

中通过

FirebaseAuth.instance.authStateChanges()

流处理认证状态变更

使用
```
flutter_secure_storage
```
存储认证令牌 —— 绝对不要存储在
```
SharedPreferences
```
或者源码中
实现规范的登出逻辑：清空本地缓存、跳转至登录页、销毁用户专属的BLoCs

Firestore

Use
```
cloud_firestore
```
for remote data persistence
DataSources wrap all Firestore calls (
```
get
```
,
```
set
```
,
```
update
```
,
```
delete
```
,
```
snapshots
```
)
Use typed model classes with
```
fromFirestore
```
/
```
toFirestore
```
factory methods
Prefer
```
.withConverter<T>()
```
for type-safe collection references
Use batch writes for multi-document operations — never multiple sequential writes
Implement offline persistence (enabled by default on mobile)

使用
```
cloud_firestore
```
实现远程数据持久化
DataSource层封装所有Firestore调用（
```
get
```
、
```
set
```
、
```
update
```
、
```
delete
```
、
```
snapshots
```
）
使用带
```
fromFirestore
```
/
```
toFirestore
```
工厂方法的类型化模型类
优先使用
```
.withConverter<T>()
```
获取类型安全的集合引用
多文档操作使用批量写入 —— 绝对不要执行多次顺序写入
实现离线持久化（移动端默认已开启）

Security Rules

安全规则

NEVER rely on client-side validation alone — enforce rules in Firestore Security Rules
Default deny: start with
```
allow read, write: if false;
```
and open only what's needed
Always validate
```
request.auth != null
```
for authenticated-only collections
Test rules with the Firebase Emulator Suite before deploying

绝对不要只依赖客户端校验 —— 必须在Firestore安全规则中强制校验
默认拒绝所有访问：初始规则设置为
```
allow read, write: if false;
```
，仅开放必要的权限
针对仅允许认证用户访问的集合，必须校验
```
request.auth != null
```
部署前使用Firebase Emulator Suite测试规则

Push Notifications (FCM)

推送通知（FCM）

Use
```
firebase_messaging
```
for push notifications
Request notification permissions early but gracefully (explain value before requesting)
Handle foreground, background, and terminated-state messages separately
Store FCM token in Firestore user document for server-side targeting
Re-register token on
```
onTokenRefresh
```
stream

使用
```
firebase_messaging
```
实现推送通知功能
尽早且友好地申请通知权限（申请前先向用户说明权限价值）
分别处理前台、后台、应用终止三种状态下的消息
将FCM令牌存储在Firestore的用户文档中，用于服务端定向推送
监听
```
onTokenRefresh
```
流，令牌刷新时重新注册

Crashlytics

Use
```
firebase_crashlytics
```
for crash reporting
Enable in staging and production flavors only — disable in dev

Record Flutter errors:

FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError

Catch async errors via
```
PlatformDispatcher.instance.onError
```

Add custom keys for user context:

Crashlytics.instance.setCustomKey('userId', id)

使用
```
firebase_crashlytics
```
实现崩溃上报
仅在预发和生产环境开启 —— 开发环境关闭

记录Flutter错误：

FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError

通过
```
PlatformDispatcher.instance.onError
```
捕获异步错误

增加用户上下文自定义键：

Crashlytics.instance.setCustomKey('userId', id)

Analytics

Use
```
firebase_analytics
```
for user behavior tracking

Log meaningful events with descriptive names:

analytics.logEvent(name: 'purchase_completed')

Set user properties for segmentation:

analytics.setUserProperty(name: 'plan', value: 'premium')

Track screen views via
```
FirebaseAnalyticsObserver
```
in
```
GoRouter
```
NEVER log PII (emails, passwords, phone numbers) in analytics events

使用
```
firebase_analytics
```
实现用户行为追踪

记录语义清晰的有效事件：

analytics.logEvent(name: 'purchase_completed')

设置用户属性实现用户分群：

analytics.setUserProperty(name: 'plan', value: 'premium')

在
```
GoRouter
```
中通过
```
FirebaseAnalyticsObserver
```
追踪页面浏览
绝对不要在分析事件中记录个人可识别信息（邮箱、密码、手机号）

Remote Config

远程配置

Use
```
firebase_remote_config
```
for feature flags and A/B testing
Set sensible defaults locally — app MUST work without Remote Config fetched
Fetch and activate on app start with a timeout fallback
Cache values and respect minimum fetch intervals to avoid throttling

使用
```
firebase_remote_config
```
实现功能开关和A/B测试
本地设置合理的默认值 —— 就算没有拉取到远程配置，应用也必须能正常运行
应用启动时拉取并激活配置，设置超时兜底逻辑
缓存配置值，遵守最小拉取间隔要求避免被限流