Firebase Performance监控卡顿教程 - 第2节 Firebase Performance监控卡顿教程 - 第2节

📚 课程目录第2章 Firebase项目与App关联

## 2. Firebase 项目与 App 关联：创建项目、注册应用、下载配置文件、集成基础库本章是搭建 Firebase Performance 监控的基础。只有将 Android / iOS 应用正确关联到 Firebase 项目，并导入配置文件与基础 SDK，后续的卡顿监控才能正常运行。整个过程分为 **控制台操作** 和 **客户端集成** 两个阶段，下面按步骤拆解。 ### 2.1 整体流程

### 2.2 创建 Firebase 项目访问 [Firebase 控制台](https://console.firebase.google.com)，点击 **「添加项目」**，按向导填写项目名称（建议与 App 包名或 Bundle ID 对应）、启用或禁用 Google Analytics（推荐启用，可配合 BigQuery 分析卡顿数据）。 >

> 💡 提示： 项目名称在创建后不可修改，但后续可在项目设置中更改显示名称。名称限制 30 个字符以内，建议使用英文+数字组合。 >

**关键参数对照表：** | 配置项 | 说明 | 建议值 | |--------|------|--------| | 项目名称 | 唯一标识，与内部资源绑定 | `monitoring-tutorial` | | 国家/地区 | 影响数据存储位置 | 选择离用户最近区域（如 `asia-east2`） | | Google Analytics | 开启后自动打点 | ✅ 开启（使用默认账号） | ### 2.3 注册应用并下载配置文件在项目控制台首页点击 **Android** 或 **iOS** 图标，输入对应平台的应用信息。 | 平台 | 必填字段 | 配置文件 | 关键注意事项 | |------|---------|---------|-------------| | Android | 包名 (Package Name) | `google-services.json` | 必须与 `AndroidManifest.xml` + `build.gradle` 中的 `applicationId` 完全一致 | | iOS | Bundle ID | `GoogleService-Info.plist` | 必须与 Xcode 项目中的 Bundle Identifier 一致 (包括大小写) |

⚠️ 重要： 配置文件包含 、项目 ID 等敏感信息，禁止 上传至公开仓库（如 GitHub）。建议在 `.gitignore` 中添加对应规则：

# .gitignore 示例
google-services.json
GoogleService-Info.plist

配置文件下载后，直接拖入 Android 项目的 **app/** 目录（或 iOS 项目的 Xcode 根目录）。如果后续需要切换 Firebase 项目，只需替换该文件并重新构建即可。 ### 2.4 集成 Firebase 基础库 #### 2.4.1 Android 集成（Gradle） **项目级 `build.gradle`（或 `settings.gradle`）：**

buildscript {
    dependencies {
        // 添加 Google Services 插件
        classpath 'com.google.gms:google-services:4.4.0'
    }
}

**模块级 `app/build.gradle`：**

apply plugin: 'com.google.gms.google-services'

android {
    // ...
}

dependencies {
    // Firebase 基础库
    implementation platform('com.google.firebase:firebase-bom:32.7.0')
    // Performance 监控库（后续章节会详细展开）
    implementation 'com.google.firebase:firebase-perf'
}

❌ 常见错误： 如果未在 app/build.gradle 最底部添加 apply plugin: 'com.google.gms.google-services'，则 google-services.json 不会生效。运行时可能出现 DynamiteModule 或 Missing google-services.json 异常。

#### 2.4.2 iOS 集成（CocoaPods / SPM） **Podfile** 示例：

platform :ios, '13.0'

target 'YourAppTarget' do
  use_frameworks!

  pod 'FirebaseCore'
  pod 'FirebasePerformance'   # 性能监控库
end

然后执行 `pod install`。SwiftUI / UIKit 项目中，在 `AppDelegate` 或 `@main` 入口调用 `FirebaseApp.configure()`。 **初始化验证代码（可放在调试模式下）：**

import FirebaseCore

// 在 application(_:didFinishLaunchingWithOptions:) 中调用
FirebaseApp.configure()

// 可选：检查配置是否成功
if FirebaseApp.app() != nil {
    print("✅ Firebase 初始化成功")
} else {
    print("❌ Firebase 初始化失败，请检查配置文件")
}

### 2.5 配置验证与调试 **步骤清单：** 1. **清理并重新构建项目**（Android: `Build → Clean Project`；iOS: `Cmd+Shift+K`） 2. **确认 `google-services.json` 或 `GoogleService-Info.plist` 被正确解析** - Android 构建后可在 `app/build/generated/res/google-services` 下看到解析后的 `values.xml` 3. **运行 App，观察 Logcat 或 Xcode 控制台** - 正常输出：`Firebase App [DEFAULT] - ready` - 异常输出：`Configuration fails: Missing GoogleService-Info.plist` 4. **检查 Performance 自动采集是否启动**（无需手动调用，集成基础库后自动启用）

🔧 调试技巧： 使用 Firebase 调试视图（`adb shell setprop debug.firebase.analytics.app 包名`）可以实时查看 SDK 初始化日志。

### 2.6 常见错误与解决方案 | 错误现象 | 原因 | 解决方法 | |---------|------|----------| | `Default FirebaseApp is not initialized` | 未调用 `FirebaseApp.initializeApp()` 或配置文件缺失 | 检查配置文件位置 + 确保在 `Application.onCreate()` 或 AppDelegate 中初始化 | | `google-services.json` 解析失败 | JSON 格式损坏或版本不匹配 | 重新从控制台下载，不要手动修改文件 | | `Cannot resolve symbol 'FirebasePerformance'` | 未添加 Performance BOM 依赖 | 在 `app/build.gradle` 中补充 `implementation platform(...)` | | iOS 构建时 `Module 'Firebase' not found` | CocoaPods 未正确导入 | 执行 `pod deintegrate && pod install` 重新安装 | | 运行时 `401 Unauthorized` 网络错误 | 受限制（未绑定应用包名） | 在 Firebase 项目设置中添加 SHA-1 指纹（Android）或对应 Bundle ID | ### 2.7 性能与稳定性说明 - **BOM 版本管理**：使用 `firebase-bom` 可自动对齐所有 Firebase SDK 版本，避免依赖冲突。建议定期更新 BOM 版本以获取性能优化和安全补丁。 - **初始化时机**：Firebase 基础库在 App 启动时自动初始化（默认阻塞主线程约 20-50ms）。若需精确控制启动时间，可配置 `FirebaseInitProvider` 的初始化延迟，但 *不建议* 在生产环境中关闭自动初始化。 - **多进程 App**：若 App 使用多进程，Firebase 会在每个进程中创建独立实例。建议只在主进程进行初始化，避免重复创建资源。完成本章操作后，你的 App 已具备 Firebase 基础服务能力，下一章将重点介绍 **Performance SDK 的单独配置与监控开关**。