企业官网建设流程全解析

FirebasePerformance 开发测试 App（TestApp）搭建与运行指南：Prod/Autopush 双环境配置实战

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk

本文以 firebase-ios-sdk 仓库中 FirebasePerformance/Tests/TestApp/README.md 为骨架，系统讲解 Firebase Performance 官方开发测试 App（PerfTestRigApp）的完整搭建流程：如何为 Prod（生产）与 Autopush（预发）两种上报环境创建 Firebase 工程、放置GoogleService-Info.plist、用generate_project.sh一键生成 Xcode 工程并运行。读完本文，你将掌握 Firebase Performance SDK 开发调试环境的完整搭建方法，并理解FPR_AUTOPUSH_ENV环境变量在 SDK 内部的真实作用链路。

一、TestApp 是什么：Firebase Performance 的"性能实验台"

FirebasePerformance/Tests/TestApp 是 firebase-ios-sdk 仓库中 Firebase Performance 模块自带的开发测试 App（工程名 PerfTestRigApp，target 名为FirebasePerformance-TestApp）。它不是普通的示例工程，而是专门用于在开发阶段验证、调试、压测 Firebase Performance SDK 各项采集能力的实验台，其主要用途包括：

• Trace（自定义追踪）测试：手动创建、启动、停止自定义 Trace，验证指标与计数器上报；
• 网络请求测试：覆盖 8 种不同的网络请求实现方式，验证 SDK 的网络自动采集与过滤逻辑；
• 屏幕追踪（Screen Trace）测试：通过快速/慢速大表格、卡帧页面等场景，验证UIViewController生命周期追踪、滑动卡顿与帧丢失检测；
• 开发期诊断：开启FPRDiagnosticsLocal等调试开关，在本地观察 SDK 的诊断日志。

整个 TestApp 围绕 SDK 的三大采集能力组织，其 UI 由三个 Tab 构成（见 AppDelegate.m）：Traces（自定义追踪）、Requests（网络请求）、Screen Traces（屏幕追踪）。

二、环境概念：Prod 与 Autopush 的区别

Firebase Performance 的指标数据会上报到 Google 的后端服务，而 SDK 根据运行环境将数据发往不同 log source：

两个环境的核心差异体现在 SDK 的 log source 选择逻辑中。在 FPRConfigurations.m 的logSource实现中，优先级为：

1. 若进程环境变量FPR_AUTOPUSH_ENV == "1"，始终返回 461（Autopush）；
2. 否则优先使用 Remote Config 拉取到的 log source 值；
3. 否则使用GULUserDefaults缓存的旧值；
4. 兜底返回默认值 462（Prod）。

因此，对于外部开发者而言，README 明确指出：Autopush 环境产生的事件经由 Google 的 staging 服务器处理，不会出现在 Firebase 控制台中，仅适用于 Google 内部验证。绝大多数第三方场景使用 Prod 环境即可（"This should be sufficient for most scenarios"）。

三、Setup：创建 Firebase 工程与放置配置文件

3.1 Prod 环境

1. 在 Firebase 控制台创建一个新工程；
2. 添加一个iOS App，Bundle ID 必须填写com.google.FIRPerfTestApp（App 的 Bundle ID 与 Firebase 工程中的 iOS App 标识必须严格一致，SDK 初始化时才能匹配到正确的配置）；
3. 下载该 iOS App 的GoogleService-Info.plist；
4. 将其放入仓库的FirebasePerformance/Tests/TestApp/Plists/Prod/FIRPerfTestApp/目录下。

3.2 Autopush 环境

1. 创建另一个 Firebase 工程（或使用同一个工程新建 App）；
2. 添加 iOS App，Bundle ID 填写com.google.FIRPerfTestAppAutopush；
3. 下载GoogleService-Info.plist，放入FirebasePerformance/Tests/TestApp/Plists/Autopush/FIRPerfTestAppAutopush/目录下。

注意：Plists目录本身不包含在仓库中（仓库只读且未跟踪该目录），需要开发者自行创建目录并放入文件。但 Xcode 工程 project.pbxproj 中已预先建立了Plists/Prod/FIRPerfTestApp与Plists/Autopush/FIRPerfTestAppAutopush两个文件组引用，并各包含一个GoogleService-Info.plist资源引用，因此只要按上述路径放置文件，重新生成工程后即可被自动打包进 App。

3.3 双环境配置文件如何在工程中共存

同一份 Xcode 工程里同时引用了两份GoogleService-Info.plist（见 pbxproj 中的两个GoogleService-Info.plist in Resources构建阶段）。实际生效哪一份，取决于生成工程时选择的-e参数：generate_project.sh会根据环境设置FPR_AUTOPUSH_ENV，而 Podfile 依赖与资源配置由pod gen依据环境变量生成，最终编译进 App 的是对应环境目录下的配置文件。

四、Build：用 generate_project.sh 生成 Xcode 工程

4.1 命令与参数

在FirebasePerformance目录下执行 generate_project.sh：

# 生成 Prod 环境工程 sh generate_project.sh -e "prod" # 生成 Autopush 环境工程（默认值，两种写法等价） sh generate_project.sh sh generate_project.sh -e "autopush"

脚本支持三个参数（见 generate_project.sh 的 help 输出）：

4.2 脚本背后的关键逻辑

脚本的核心工作是通过CocoaPods 的pod gen命令从FirebasePerformance.podspec生成独立 Xcode 工程：

pod gen "$DIR/FirebasePerformance.podspec" --local-sources="$DIR/" \ --auto-open --gen-directory="$DIR/gen" --platforms="$platform"

• --local-sources="$DIR/"：以仓库根目录为本地 spec 源，保证生成的工程引用的是当前 checkout 的 FirebasePerformance 源码，而非线上发布的 pod 版本，这正是开发调试的前提；
• --auto-open：生成后自动用 Xcode 打开工程；
• --gen-directory="$DIR/gen"：生成的工程位于仓库根目录的gen/下。

在调用pod gen之前，脚本还设置两个关键环境变量，它们会通过pod gen注入到生成的工程环境中：

export FPR_UNSWIZZLE_AVAILABLE="1" # 开发期允许反 swizzle，供单元测试使用 if [ "autopush" == "$env" ]; then export FPR_AUTOPUSH_ENV="1" # Autopush 环境标识 else export FPR_AUTOPUSH_ENV="0" fi

• FPR_UNSWIZZLE_AVAILABLE：开发期开关，使 SDK 的 swizzle 可以被撤销，便于单元测试隔离；
• FPR_AUTOPUSH_ENV：决定数据上报目标的核心开关。SDK 在初始化时读取该变量：在 FPRClient.m 中，若FPR_AUTOPUSH_ENV == "1"，则useAutoPush = YES，构建的FPRConfiguration会携带 autopush 标识；随后FPRConfigurations.m的logSource据此返回 461（Autopush）而非 462（Prod）。

注意脚本中的rm -f "$DIR/FirebasePerformance/ProtoSupport/*.[hm]"与protoc调用只在-c（clean）模式下执行：clean 模式会删除 Protogen 生成文件并调用protoc重新生成perf_metric.pbobjc，适用于需要强制重新生成 proto 代码的场景。

4.3 依赖要求

TestApp 的 Podfile 声明：

platform :ios, '15.0' target 'PerfTestRigApp' do pod 'FirebasePerformance' target 'PerfTestRigAppTests' do inherit! :search_paths pod 'EarlGrey' end end

• 最低系统版本 iOS 15.0；
• 依赖FirebasePerformancepod（本地源码）；
• 单元测试 target 额外引入EarlGrey（Google 的 iOS UI 自动化测试框架），用于PerfControllerTests.m等 UI 级测试。

五、Run：运行测试 App

工程生成并打开后：

1. 在 Xcode 中选择FirebasePerformance-TestApp这个 target（即 Podfile 中的PerfTestRigApp）；
2. 选择目标设备/模拟器；
3. 点击 Run。

App 启动时会先执行 AppDelegate.m 的初始化逻辑：

[[NSUserDefaults standardUserDefaults] setBool:YES forKey:@"FPRDelegateSwizzling"]; [[NSUserDefaults standardUserDefaults] setBool:YES forKey:@"FPRNSURLConnection"]; [[NSUserDefaults standardUserDefaults] setBool:YES forKey:@"FPRDiagnosticsLocal"]; [FIRApp configure];

这里通过NSUserDefaults显式开启了三个 SDK 调试开关：

随后[FIRApp configure]完成 Firebase 初始化，并注册三个功能 Tab：

• Traces：手动创建自定义 Trace 的试验入口（对应 TracesViewController.m）；
• Requests：网络请求压测入口，可选 8 种请求实现；
• Screen Traces：屏幕追踪压测入口，含快速/慢速大表格、卡帧页面等场景（见 ScreenTraceTestViewControllers 下的FastLargeTableViewController、SlowLargeTableViewController、FrozenFramesViewController）。

六、测试 App 的核心实验能力

6.1 网络请求测试：覆盖 8 种实现方式

网络请求列表来自 network_connections.plist，其中定义了 8 种网络连接类型，全部指向同一个 HTTPS PDF 下载地址，用于验证 SDK 对不同网络 API 的自动采集：

• PerfURLConnectionWithDelegateClassInit（NSURLConnection + Delegate，class 初始化）
• PerfURLConnectionWithDelegate（NSURLConnection + Delegate）
• PerfURLConnectionWithDelegateStartImmediately（NSURLConnection + Delegate，立即启动）
• PerfURLConnectionAsyncRequest（NSURLConnection 异步请求）
• PerfURLSessionDataTask/PerfURLSessionDataTaskWithDelegate（NSURLSession DataTask，普通 / 带 Delegate）
• PerfURLSessionDownloadTask/PerfURLSessionDownloadTaskWithDelegate（NSURLSession DownloadTask，普通 / 带 Delegate）

对应的实现类全部位于 Networking 目录，可用于逐个验证 SDK 对NSURLConnection与NSURLSession各 API 形态的采集覆盖情况。这与仓库中 SDK 侧 Instruments 单元测试（如FPRNSURLConnectionInstrumentTest.m、FPRNSURLSessionInstrumentTest.m）的测试范围一一对应。

6.2 屏幕追踪与卡顿测试

Screen Traces Tab 提供三类典型性能场景：

• FastLargeTableViewController：快速滚动的数据大表格，检验快速滑动下的采集性能；
• SlowLargeTableViewController：慢速加载的大表格，制造主线程耗时；
• FrozenFramesViewController：刻意制造卡帧页面，验证 SDK 的卡顿/冻结帧检测。

结合 SDK 侧的 FPRScreenTraceTrackerTest.m 与 FPRAppActivityTrackerTest.m，可以完整理解屏幕追踪从UIViewControllerswizzle 到帧数据采集的底层链路。

6.3 自动化与无障碍支持

TestApp 对主要交互控件都暴露了accessibilityIdentifier（如TracesTab、RequestsTab、ScreenTracesTab，见 AppDelegate.m），并提供了 PerfTraceView+Accessibility.m 等辅助扩展。这意味着可以使用 EarlGrey 或 XCUITest 对 App 进行 UI 自动化操作，例如仓库中 Tests 目录 的PerfControllerTests.m所示，这对 CI 中自动生成性能数据非常关键。

七、常见问题排查

1. App 启动崩溃或提示 GoogleService-Info 缺失：确认GoogleService-Info.plist已放在正确环境目录（Plists/Prod/FIRPerfTestApp/或Plists/Autopush/FIRPerfTestAppAutopush/）后重新执行generate_project.sh生成工程，旧工程不会自动拾取新放入的 plist。
2. Bundle ID 不匹配：Firebase 控制台中的 iOS App Bundle ID 必须与目标环境完全一致（Prod 用com.google.FIRPerfTestApp，Autopush 用com.google.FIRPerfTestAppAutopush）。
3. 数据在控制台看不到：先确认你使用的是 Prod 环境（-e prod）。Autopush 环境的数据走 Google 内部 staging 服务器，外部无法查看（README 明确说明）。
4. 想切换环境但工程没变：generate_project.sh默认复用已有工程（不带-c）。切换 Prod/Autopush 时建议用-c从零重建，或确保环境变量变更被重新注入。
5. proto 代码异常：可在生成工程时追加-c，脚本会调用protoc重新生成perf_metric.pbobjc，避免 Protogen 文件与本地 proto 不一致。

八、小结

FirebasePerformance 的开发测试 App 是一套围绕 SDK 三大采集能力（自定义 Trace、网络请求、屏幕追踪）设计的完整实验环境。其搭建要点可概括为：选环境（Prod/Autopush）→ 配 plist（对应 Bundle ID 的GoogleService-Info.plist放入对应目录）→ 跑脚本（generate_project.sh -e <env>）→ 选 target 运行。理解FPR_AUTOPUSH_ENV环境变量在 generate_project.sh、FPRClient.m 与 FPRConfigurations.m 之间的传递链路，是掌握这套环境机制的关键；而 TestApp 提供的 8 种网络请求实现与三类屏幕追踪场景，则为验证和调试 Firebase Performance SDK 提供了可直接复用的实验工具。

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk