@firebase/performance-compat 兼容层全解析:v8 到模块化 SDK 的桥接与版本演进

原创2026-10-15 21:37:061,710 阅读
文章标签:开发工具后端

@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 firebase package.

也就是说:

  • 它是一个兼容包,作用是"复刻 v8 API",即把 Firebase 9 之后模块化 SDK 的树摇友好接口,重新包装成 v8 时代命名空间式(firebase.performance())的调用形式;
  • 它不面向直接使用,开发者应当通过官方的 firebase 聚合包来间接使用它。

在 monorepo 结构上,它属于 packages 下的一个独立子包,目录结构与配套文件如下:

二、底层原理:三层结构把 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-compat provider 提供 FirebaseApp;
  • performance provider 提供模块化的 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 兼容体系的骨架。

登录后查看全文
firebase-js-sdk