@firebase/performance-compat 兼容层全解析:v8 到模块化 SDK 的桥接与版本演进
@firebase/performance-compat 兼容层全解析:v8 到模块化 SDK 的桥接与版本演进
@firebase/performance-compat 是 Firebase JavaScript SDK 中负责把 v8 风格 API 重新映射到模块化 Performance 包上的兼容层(compat package)。本文以该包的 CHANGELOG.md 为主线,结合其源码、测试与构建配置,完整梳理它从 0.1.0 到 0.2.27 的演进脉络,并讲清它"如何用一层薄封装让旧代码继续跑起来"的底层原理。读完本文,你将能够:准确理解 compat 包与 @firebase/performance 模块化包的调用关系与版本联动规则,看懂 changelog 中每次"Updated dependencies"背后发生了什么,并在实际应用中正确选用 v8 兼容 API。
一、它是什么:专为"旧 API 续命"而存在的兼容包
README.md 对该包的定位写得很直白:
This is the compat package that recreates the v8 APIs. This package is not intended for direct usage, and should only be used via the officially supported
firebasepackage.
也就是说:
- 它是一个兼容包,作用是"复刻 v8 API",即把 Firebase 9 之后模块化 SDK 的树摇友好接口,重新包装成 v8 时代命名空间式(
firebase.performance())的调用形式; - 它不面向直接使用,开发者应当通过官方的 firebase 聚合包来间接使用它。
在 monorepo 结构上,它属于 packages 下的一个独立子包,目录结构与配套文件如下:
- packages/performance-compat/src/index.ts —— 组件注册与命名空间增强入口
- packages/performance-compat/src/performance.ts —— 核心兼容实现
PerformanceCompatImpl - packages/performance-compat/src/performance.test.ts —— 兼容层单元测试
- packages/performance-compat/rollup.config.js —— 双格式(ESM/CJS)构建配置
- packages/performance-compat/package.json —— 包元信息与依赖声明
二、底层原理:三层结构把 v8 API 桥接到模块化实现
要理解这个包"为什么存在",需要先看清它内部的三个层次。整个兼容层可以概括为:命名空间增强(模块声明)→ 组件注册(依赖注入)→ 委托转发(delegate)。
1. 命名空间增强:让 firebase.performance() 重新可用
src/index.ts 末尾通过 TypeScript 模块声明(declare module)为 @firebase/app-compat 增强了两个入口:
declare module '@firebase/app-compat' {
interface FirebaseNamespace {
performance: {
(app?: FirebaseApp): FirebasePerformanceCompat;
};
}
interface FirebaseApp {
performance(): FirebasePerformanceCompat;
}
}
这意味着在 v8 兼容入口下,开发者既可以写全局的 firebase.performance(),也可以写 app 实例方法 app.performance(),两种形态最终都解析到同一个 FirebasePerformanceCompat 类型。
2. 组件注册:通过 component 体系注入服务
src/index.ts 中的 registerPerformanceCompat 负责把兼容服务挂载到 Firebase 的依赖注入容器上:
firebaseInstance.INTERNAL.registerComponent(
new Component(
'performance-compat',
performanceFactory,
ComponentType.PUBLIC
)
);
工厂函数 performanceFactory 从容器中取出两个实例:
app-compatprovider 提供FirebaseApp;performanceprovider 提供模块化的FirebasePerformance(来自@firebase/performance)。
然后把它们一起塞进 PerformanceCompatImpl。这里"取 performance provider 一定会成功"的原因在于:@firebase/performance 本身也是一个注册在容器里的 PUBLIC 组件(见 packages/performance/src/index.ts 的 registerPerformance())。
3. 委托转发:compat 对象只是模块化对象的"薄壳"
src/performance.ts 定义了核心类 PerformanceCompatImpl,它同时实现 FirebasePerformanceCompat 与 _FirebaseService,但内部不持有任何业务逻辑,所有能力都转发给模块化 _delegate:
export class PerformanceCompatImpl
implements FirebasePerformanceCompat, _FirebaseService
{
constructor(
public app: FirebaseApp,
readonly _delegate: FirebasePerformance
) {}
get instrumentationEnabled(): boolean {
return this._delegate.instrumentationEnabled;
}
set instrumentationEnabled(val: boolean) {
this._delegate.instrumentationEnabled = val;
}
// dataCollectionEnabled 同理……
trace(traceName: string): PerformanceTrace {
return trace(this._delegate, traceName);
}
}
trace() 直接调用模块化包里导出的 trace(performance, name) 函数(定义见 packages/performance/src/index.ts),后者内部创建 Trace 实例(见 packages/performance/src/resources/trace.ts),通过 start()/stop() 打点、计算耗时并记录到日志。
单元测试 src/performance.test.ts 恰好验证了这三层桥接行为:
- 设置
instrumentationEnabled = false会真实写到模块化对象上(默认值都是true,见 test/util.ts); - 设置
dataCollectionEnabled = false同样转发; - 调用
performanceCompat.trace('test')时,spy 断言模块化的trace以(fakeModularPerformance, 'test')被调用。
也就是说,compat 层不复制逻辑,只做路由——这正是 v8 兼容体系的一贯设计。
三、Changelog 全景:从模块化发布到 0.2.27 的关键里程碑
CHANGELOG 记录了这个包从 0.1.0(随模块化 SDK 发布)到 0.2.27 的完整版本历史。整体可以归纳为几条主线:SDK 形态转变、构建产物现代化、TypeScript 升级、依赖同步、兼容性修复。
1. 起点 0.1.0:模块化 SDK 发布
- 0.1.0(PR #5345,修复 #5015)—— "Release modularized SDKs":这是 compat 包的诞生时刻。v8 时代的
firebase.performance()命名空间 API 被拆成模块化 API 之后,compat 包负责让旧调用方式继续可用。同期依赖@firebase/performance@0.5.0、@firebase/performance-types@0.1.0。
2. 早期稳定性修复
- 0.1.1(PR #5506)—— "Performance could encounter runtime errors when initialized in certain environments":修复了在特定环境下初始化 Performance 可能抛运行时错误的问题。这是 changelog 中少有的功能性 bug 修复条目,其余多数为依赖与构建更新。
3. exports 字段与类型声明:包格式现代化
这一阶段解决了 npm 包在 ESM/CommonJS 混合生态下的解析问题:
- 0.1.3(PR #5693)—— 为所有包添加
exports字段; - 0.1.4(PR #5708,修复 #1487)—— 更新构建脚本以适配
exports字段; - 0.1.10(PR #6307,修复 #6300)—— 在
exports字段中补充类型声明(type declarations),保证 TypeScript 消费者能解析到.d.ts。
这些改动在 package.json 中留下了痕迹:exports["."] 同时提供 types、require(dist/index.cjs.js)与 default(dist/esm/index.esm.js)三个入口。
4. 构建目标演进:ES2017 → ES2020
- 0.2.10(PR #8475)—— "Remove ES5 bundles. The minimum required ES version is now ES2017":移除 ES5 产物,最低支持 ES2017;
- 0.2.21(PR #9167)—— "Set build targets to ES2020":构建目标提升到 ES2020。
对应地,rollup.config.js 中 typescriptPlugin 的 tsconfigOverride 将 target 硬编码为 es2020,并排除 **/*.test.ts。同时构建产物分 ESM 与 CJS 两路输出,且所有 peerDependencies/dependencies 都被声明为 external(rollup.config.js),保证依赖不被重复打包。
5. TypeScript 版本升级路线
- 0.1.16(PR #6682)与 0.2.0(PR #6799)—— 升级 TypeScript 到 4.7.4;
- 0.2.11(PR #8604)—— 升级到 TypeScript 5.5.4。
当前 package.json 中 typescript 为 5.5.4,与 changelog 最后一条一致。
6. 依赖与元数据收尾
- 0.2.6(PR #8079)—— 将各包
repository.url字段更新为 NPM 偏好的格式; - 0.2.7(PR #8237)—— "Bump all packages so staging works":统一提升版本以配合发布流水线;
- 0.2.26(PR #10097)—— 为 compat 包添加
@firebase/app作为peerDependency,确保与 app 包版本约束清晰(见 package.json,peerDependencies 包含@firebase/app: 0.x与@firebase/app-compat: 0.x); - 0.2.27(PR #10293)—— 更新大量顶层
devDependencies,是当前最新版本。
7. 完整版本速查表
为便于检索,下表汇总了 changelog 中全部版本及其关键变化(依赖更新一栏合并展示):
| 版本 | 主要变更 | 同步更新的依赖(节选) |
|---|---|---|
| 0.2.27 | 更新顶层 devDependencies(#10293) | component@0.7.5、logger@0.5.2、performance@0.7.14、performance-types@0.2.5、util@1.15.3 |
| 0.2.26 | 为 compat 包添加 @firebase/app peerDependency(#10097) |
util@1.15.2、component@0.7.4、performance@0.7.13 |
| 0.2.25 | 更新依赖(#9883) | component@0.7.3、logger@0.5.1、performance@0.7.12、util@1.15.1 |
| 0.2.24 | 依赖更新 | util@1.15.0、performance@0.7.11、component@0.7.2 |
| 0.2.23 | 依赖更新 | util@1.14.0、performance@0.7.10、component@0.7.1 |
| 0.2.22 | 依赖更新 | performance@0.7.9 |
| 0.2.21 | 构建目标设为 ES2020(#9167) | performance@0.7.8、component@0.7.0、logger@0.5.0、util@1.13.0 |
| 0.2.20 | 依赖更新 | util@1.12.1、component@0.6.18、performance@0.7.7 |
| 0.2.19 | 依赖更新 | util@1.12.0、component@0.6.17、performance@0.7.6 |
| 0.2.18 | 依赖更新 | util@1.11.3、component@0.6.16、performance@0.7.5 |
| 0.2.17 | 依赖更新 | util@1.11.2、component@0.6.15、performance@0.7.4 |
| 0.2.16 | 依赖更新 | util@1.11.1、performance@0.7.3、component@0.6.14 |
| 0.2.15 | 依赖更新 | performance@0.7.2 |
| 0.2.14 | 依赖更新 | util@1.11.0、performance@0.7.1、component@0.6.13 |
| 0.2.13 | 依赖更新 | performance@0.7.0 |
| 0.2.12 | 依赖更新 | util@1.10.3、component@0.6.12、performance@0.6.12 |
| 0.2.11 | 升级 TypeScript 5.5.4(#8604) | component@0.6.11、logger@0.4.4、performance@0.6.11、performance-types@0.2.3、util@1.10.2 |
| 0.2.10 | 移除 ES5 产物,最低 ES2017(#8475) | performance@0.6.10、component@0.6.10、logger@0.4.3、util@1.10.1 |
| 0.2.9 | 依赖更新 | util@1.10.0、component@0.6.9、performance@0.6.9 |
| 0.2.8 | 依赖更新 | util@1.9.7、component@0.6.8、performance@0.6.8 |
| 0.2.7 | 统一版本以支持 staging(#8237) | component@0.6.7、logger@0.4.2、performance@0.6.7、util@1.9.6 |
| 0.2.6 | repository.url 更新为 NPM 偏好格式(#8079) |
performance-types@0.2.1、performance@0.6.6、component@0.6.6、logger@0.4.1、util@1.9.5 |
| 0.2.5 ~ 0.2.2 | 依赖更新 | util/component/performance 同步 |
| 0.2.1 | 依赖更新 | util@1.9.0、component@0.6.1、performance@0.6.1 |
| 0.2.0 | 升级 TypeScript 4.7.4(#6799) | util@1.8.0、component@0.6.0、logger@0.4.0、performance@0.6.0、performance-types@0.2.0 |
| 0.1.17 | 依赖更新 | performance@0.5.17 |
| 0.1.16 | 升级 TypeScript 4.7.4(#6682) | component@0.5.21、logger@0.3.4、performance@0.5.16、performance-types@0.1.1、util@1.7.3 |
| 0.1.15 ~ 0.1.12 | 依赖更新 | util/component/performance 同步 |
| 0.1.11 | 依赖更新 | util@1.6.2、component@0.5.16、performance@0.5.11 |
| 0.1.10 | exports 字段补充类型声明(#6307,#6300) |
component@0.5.15、logger@0.3.3、performance@0.5.10、util@1.6.1 |
| 0.1.9 ~ 0.1.5 | 依赖更新 | util/component/performance 同步 |
| 0.1.4 | 构建脚本适配 exports 字段(#5708,#1487) |
component@0.5.9、logger@0.3.2、performance@0.5.4、util@1.4.2 |
| 0.1.3 | 为所有包添加 exports 字段(#5693) |
component@0.5.8、logger@0.3.1、performance@0.5.3、util@1.4.1 |
| 0.1.2 | 依赖更新 | performance@0.5.2 |
| 0.1.1 | 修复特定环境下初始化报错(#5506) | logger@0.3.0、util@1.4.0、performance@0.5.1、component@0.5.7 |
| 0.1.0 | 发布模块化 SDK(#5345,#5015) | performance@0.5.0、performance-types@0.1.0 |
从这张表可以清晰看到 compat 包的版本节奏:绝大多数版本是"依赖更新"(Updated dependencies),真正改变行为的是 0.1.0、0.1.1、0.1.3/0.1.4/0.1.10(exports/类型)、0.2.10/0.2.21(构建目标)、0.2.26(peerDependency)这几个节点。
四、版本联动机制:为什么 changelog 里全是"Updated dependencies"
@firebase/performance-compat 的依赖面由 package.json 明确列出:
@firebase/performance(模块化实现,当前 0.7.14)@firebase/performance-types(共享类型定义,当前 0.2.5)@firebase/component(组件注册体系,当前 0.7.5)@firebase/logger(日志工具,当前 0.5.2)@firebase/util(通用工具,当前 1.15.3)tslib(TS 运行时辅助库)
由于 compat 包是"转发壳",它自身的稳定版更新几乎完全取决于上游模块化包的节奏:@firebase/performance 每发一个版本,compat 包就要跟着 bump 一次并同步发布,这正是 changelog 中大量 "Updated dependencies" 条目的由来。例如 0.2.13 到 0.2.22 之间,几乎每一条都对应 performance 从 0.7.0 到 0.7.9 的逐步升级。
从源码层面看,这个"薄壳"依赖面很小:performance.ts 只 import 了模块化包的 trace、FirebasePerformance、PerformanceTrace,以及 @firebase/performance-types 与 @firebase/app-compat。这也解释了为什么 compat 包的版本号(0.2.x)与模块化包(0.7.x)各自独立——它们遵循同一套 release 流水线,但版本号互不绑定。
五、实践:在应用中如何使用与验证
1. 通过 firebase 聚合包使用
按照 README 的说明,不要直接 import @firebase/performance-compat,而是通过官方 firebase 包。在仓库里,v8 兼容入口的组装在 packages/firebase/compat/performance/index.ts 完成——这个文件只有一行有效代码:
import '@firebase/performance-compat';
它被 packages/firebase/compat/index.ts 等入口引入,从而在 import firebase from 'firebase/compat' 之后即可使用 firebase.performance() 与 app.performance()。
典型用法如下:
import firebase from 'firebase/compat';
import 'firebase/compat/performance';
const perf = firebase.performance();
// 控制自动埋点(页面加载、网络请求等)与自定义 trace 的数据采集
perf.instrumentationEnabled = true;
perf.dataCollectionEnabled = true;
// 创建自定义 trace
const t = perf.trace('checkout_flow');
t.start();
// ……业务逻辑……
t.stop();
2. 两个开关的含义
FirebasePerformance 接口(见 packages/performance/src/public_types.ts)暴露两个布尔开关:
instrumentationEnabled—— 控制自动 trace 与 HTTP/S 网络监控的采集;dataCollectionEnabled—— 控制自定义 trace 的采集。
这两个开关最终落到模块化包的 SettingsService 上(见 packages/performance/src/controllers/perf.ts),并在初始化时接受 PerformanceSettings 的覆盖(packages/performance/src/index.ts 的 initializePerformance)。注意:模块化 SDK 要求默认 app([DEFAULT])才能初始化 Performance,非默认 app 会抛 FB_NOT_DEFAULT,且不支持 Node.js 环境(无 window 时报 NO_WINDOW)。
3. 本地构建与测试
如果你在本地阅读源码,可以按如下方式验证兼容层行为(仓库为只读,仅说明查看与运行方式):
- 构建:
cd packages/performance-compat && yarn build(走 rollup.config.js 输出dist/index.cjs.js与dist/esm/index.esm.js); - 单测:
yarn test(vitest 运行 src/performance.test.ts 中的桥接断言); - 类型检查:
yarn trusted-type-check(基于 tsec 与 tsconfig.json)。
六、总结
透过 @firebase/performance-compat 的 CHANGELOG 与源码,可以看到一条清晰的工程主线:在模块化 SDK 改造进程中,用一个零业务逻辑的委托壳(PerformanceCompatImpl)加一个命名空间增强(declare module)加一次组件注册(Component('performance-compat')),完整保留 v8 时代的 firebase.performance() 调用体验。changelog 中的版本号跳跃,绝大多数是上游 @firebase/performance 演进(0.5.x → 0.7.x)与构建体系现代化(exports 字段、ES2017/ES2020 目标、TypeScript 5.5.4)的忠实投影;0.1.0 的模块化发布、0.1.1 的初始化修复与 0.2.26 的 peerDependency 补全,则是其中仅有的几个行为级变更节点。
对于维护旧代码或分析 SDK 体积的开发者,这条"compat 包只路由、不实现"的原则同样适用于其他 compat 包(如 auth-compat、firestore-compat),读懂一个 performance-compat,也就读懂了整个 Firebase v8 兼容体系的骨架。