flutterfire-configure

FlutterFire 配置技能

此技能介绍如何为 Flutter 应用正确设置和配置 Firebase。

使用场景

在以下情况下使用此技能：

• 首次向 Flutter 项目添加 Firebase。
• 添加新的 Firebase 服务或平台后运行 flutterfire configure。
• 在 main.dart 中初始化 Firebase。
• 为多个应用变体设置独立的 Firebase 项目。

---

1. 前置条件

安装所需工具：

npm install -g firebase-tools
firebase login
dart pub global activate flutterfire_cli

最低平台要求：

• Android：API 级别 19（KitKat）或更高版本
• Apple：iOS 11 或更高版本

---

2. 设置和配置

# From your Flutter project directory:
flutterfire configure

# Add the core Firebase package:
flutter pub add firebase_core

• 每当新增平台支持或开始使用新的 Firebase 服务时，都要重新运行 flutterfire configure。
• 对于 Android 专属服务（Crashlytics、Performance Monitoring），FlutterFire CLI 会自动添加所需的 Gradle 插件。
• 添加新的 Firebase 插件后，使用 flutter run 重新构建。

---

3. Firebase 初始化

import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}

• 在初始化 Firebase 之前调用 WidgetsFlutterBinding.ensureInitialized()。
• 在调用任何其他 Firebase 服务之前初始化 Firebase。
• 切勿手动修改 firebase_options.dart——该文件会自动生成。
• 将 firebase_options.dart 提交到版本控制中——该文件包含非机密的配置标识符。
• 对于 Firebase Emulator Suite：await Firebase.initializeApp(demoProjectId: "demo-project-id")。

---

4. 验证和最佳实践

配置完成后，验证设置是否正常工作：

1. 运行 flutter run，确认应用启动时没有 Firebase 初始化错误。
2. 检查调试控制台，确认出现 Firebase initialized successfully 或类似提示。
3. 确认 firebase_options.dart 已生成，且其中的项目 ID 正确。

• 启用 Firebase Analytics，以便与 Crashlytics、Remote Config 和其他产品配合使用时获得最佳体验。
• 所有平台使用同一个 Firebase 项目，以确保数据一致性。
• 使用某些 Firebase 服务的 iOS/macOS 应用，需在 Xcode 中添加 Keychain Sharing 功能。
• 使用调试版和发布版构建测试 Firebase 配置。
• 检查 Flutter 插件与底层 Firebase SDK 之间的版本兼容性。

---

5. 多个应用变体

为每个环境（开发、预发布、生产）创建独立的 Firebase 项目：

flutterfire config \
  --project=flutter-app-dev \
  --out=lib/firebase_options_dev.dart \
  --ios-bundle-id=com.example.flutterApp.dev \
  --ios-out=ios/flavors/dev/GoogleService-Info.plist \
  --android-package-name=com.example.flutter_app.dev \
  --android-out=android/app/src/dev/google-services.json

按应用变体集中初始化 Firebase：

// firebase.dart
import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/services.dart';
import 'package:flutter_app/firebase_options_prod.dart' as prod;
import 'package:flutter_app/firebase_options_stg.dart' as stg;
import 'package:flutter_app/firebase_options_dev.dart' as dev;

Future<void> initializeFirebaseApp() async {
  final firebaseOptions = switch (appFlavor) {
    'prod' => prod.DefaultFirebaseOptions.currentPlatform,
    'stg' => stg.DefaultFirebaseOptions.currentPlatform,
    'dev' => dev.DefaultFirebaseOptions.currentPlatform,
    _ => throw UnsupportedError('Invalid flavor: $appFlavor'),
  };
  await Firebase.initializeApp(options: firebaseOptions);
}

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initializeFirebaseApp();
  runApp(const MainApp());
}

• 使用 appFlavor 或环境变量在运行时选择配置。
• 使用命名空间别名导入各应用变体的配置（例如 as dev）。
• 使用辅助脚本自动完成多应用变体配置。

---

参考资料

• 将 Firebase 添加到 Flutter 应用
• FlutterFire CLI