开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载本文以 packages/app-compat/CHANGELOG.md 为主线完整梳理firebase/app-compat包从 0.1.0 首发到 0.5.19 的版本演进脉络——包括 exports 字段引入、CJS 构建修复、ES5 bundle 移除、构建目标提升至 ES2020、Node 引擎要求上调等关键节点。读完本文你将理解 app-compat 在 firebase-js-sdk 仓库中v8 命名空间 API 兼容层的定位并掌握其内部如何用组件容器机制把firebase.initializeApp()、firebase.app().firestore()这类旧式调用转发到模块化内核firebase/app。1. CHANGELOG 文件定位与条目结构firebase/app-compat在 packages/app-compat/README.md 中的定位描述为This is the compatibility layer for the Firebase App package, which recreates the v8 API.This package is not intended for direct usage, and should only be used via the officially supported firebase package.即它是 App 包的兼容层负责重建 v8命名空间式API且官方不建议直接依赖应通过firebase主包间接使用。仓库根目录的 CHANGELOG.md 也明确说明各包的变更历史分别位于packages/package name/CHANGELOG.md。该文件的每个版本条目遵循 changesets 约定由两类小节构成Minor Changes次版本号提升通常对应行为变化如构建目标调整、默认值变更Patch Changes修订号提升除依赖联动Updated dependencies外偶尔包含直接的代码修复并附 commit 与 PR 编号。从 0.1.0 到 0.5.19 的完整时间线中绝大多数 Patch 条目是跟随firebase/app等依赖版本联动真正需要开发者关注的是下表列出的实质变更。2. 版本演进时间线继承 CHANGELOG 全部实质条目2.1 0.1.x模块化 SDK 首发与构建体系补课版本类型变更内容0.1.0MinorRelease modularized SDKsPR #5345fixes #5015首次以模块化架构发布依赖firebase/app0.7.00.1.1Patch移除 app-compat 中的 named export 以修复 CJS 构建PR #5400fixes #2903移除 app-compat 中的 private typesPR #5385fixes #53820.1.7PatchAdd exports field to all packagesPR #5693为所有包引入exports字段0.1.8PatchUpdate build scripts to work with the exports fieldPR #5708fixes #1487构建脚本适配 exports 字段0.1.27Patchfix: add type declarations to exports fieldPR #6307fixes #6300为 exports 字段补上类型声明入口0.1.38PatchUpgrade TypeScript to 4.7.4PR #66820.1.x 阶段的四条构建修复0.1.1、0.1.7、0.1.8、0.1.27构成一条清晰主线模块化发布后围绕 Node.jsexports条件解析对 CJS/ESM/类型声明三种入口反复补漏这与下文 3.1 节package.json中最终的exports形态直接对应。2.2 0.2.x构建目标、全局作用域与类型系统版本变更内容0.2.0Update TypeScript version to 4.7.4PR #67992.29 附近0.2.30Updaterepository.urlfield in allpackage.jsonfiles to NPMs preferred formatPR #80790.2.33Bump all packages so staging worksPR #82370.2.38修复文档与内部变量/参数拼写PR #8280fixes #8279修复window存在但self不存在时 app-compat 检查失败的问题PR #8378fixes #8365场景为 Ionic Stencil 的 Jest preset0.2.39Updated how app-compat checks the global scopePR #8414fixes #84090.2.44Remove ES5 bundles. The minimum required ES version is now ES2017PR #84750.2.46Upgrade to TypeScript 5.5.4PR #8604其中 0.2.38/0.2.39 两次修复都指向入口文件中的全局作用域探测逻辑见 3.2 节源码0.2.44 起产物最低为 ES2017意味着不再面向 ES5 时代的旧浏览器。2.3 0.3.x0.5.x行为默认值、构建目标与依赖联动版本变更内容0.3.0DefaultautomaticDataCollectionEnabledto true without changing App Checks default behaviorPR #89990.3.1RevertPR #8999PR #9007——0.3.0 的默认值调整随后被回滚0.4.0重新落地 DefaultautomaticDataCollectionEnabledto true without changing App Checks default behaviorPR #90100.5.0Update node engines version to a minimum of Node 20PR #9128Set build targets to ES2020PR #91670.5.2 0.5.16以依赖联动为主期间firebase/util升至 1.15.x、firebase/component升至 0.7.x、firebase/app升至 0.16.x0.5.17Updated many top-leveldevDependenciesPR #102930.5.18依赖firebase/app0.16.20.5.19依赖firebase/app0.16.3当前仓库中的版本0.3.0 → 0.3.1 → 0.4.0 这一提出—回滚—再落地的反复值得升级时特别注意automaticDataCollectionEnabled的默认行为以 0.4.0 起的状态为准。0.5.0 之后至今的条目全部是依赖联动说明该包进入稳定期API 面不再变动。3. 结合源码理解 CHANGELOG 中反复出现的变更3.1package.jsonexports 字段与引擎要求packages/app-compat/package.json 当前版本为0.5.19关键字段如下{ name: firebase/app-compat, description: The primary entrypoint to the Firebase JS SDK, main: dist/index.cjs.js, browser: dist/esm/index.esm.js, module: dist/esm/index.esm.js, lite: dist/index.lite.js, exports: { .: { types: ./dist/app-compat-public.d.ts, require: ./dist/index.cjs.js, lite: ./dist/index.lite.js, default: ./dist/esm/index.esm.js }, ./package.json: ./package.json }, engines: { node: 24.12.0 } }exports[.]中的四个条件对应 CHANGELOG 中 0.1.7/0.1.8/0.1.27 三次修复的最终形态types指向公开发布的类型文件0.1.27 补的就是这一项、require指向 CJS 产物0.1.1 修复的 CJS 构建、0.1.8 适配 exports 的产物。lite条件入口dist/index.lite.js对应独立的 Lite 变体见 3.4 节。0.5.0 把 engines 最低要求提到 Node 20当前仓库中为24.12.0说明构建环境要求在此后继续上调该 engines 字段约束的是贡献者在仓库中运行构建/测试的 Node 版本而非浏览器端运行环境。0.5.0 的Set build targets to ES2020与 0.2.44 的最低 ES2017共同构成产物 ES 目标的下调边界演进ES5 → ES2017 → ES2020。其运行时依赖锁定为firebase/app0.16.3、firebase/util1.15.3、firebase/logger0.5.2、firebase/component0.7.5、tslib^2.1.0——CHANGELOG 中每一条 Updated dependencies 条目都体现在这份精确版本列表的推进上。3.2 入口文件全局作用域检测与重复加载告警packages/app-compat/src/index.ts 在模块加载时执行了一段保护逻辑try { const globals getGlobal(); // Firebase Lite detection if ((globals as any).firebase ! undefined) { logger.warn( Warning: Firebase is already defined in the global scope. Please make sure Firebase library is only loaded once. ); const sdkVersion ((globals as any).firebase as FirebaseNamespace).SDK_VERSION; if (sdkVersion sdkVersion.indexOf(LITE) 0) { logger.warn( Warning: You are trying to load Firebase while using Firebase Performance standalone script. ... ); } } } catch { // ignore errors thrown by getGlobal }通过firebase/util的getGlobal()实现位于 packages/util/src/global.ts跨环境取全局对象这正是 0.2.38 修复 window存在但self不存在Ionic Stencil 的 Jest preset和 0.2.39 Updated how app-compat checks the global scope 两条 changelog 所指向的检测路径探测异常被try/catch吞掉保证在非标准环境中模块仍可加载。若全局已存在firebase且其SDK_VERSION包含LITE则提示正在与 Performance 独立脚本叠加加载与 3.4 节 Lite 变体在版本串中追加_LITE后缀的做法相呼应。入口最后调用registerCoreComponents()并默认导出firebase命名空间同时具名导出_FirebaseNamespace、_FirebaseService、FirebaseApp、FirebaseNamespace等类型供其他 compat 包引用。3.3 命名空间与组件注册v8 API 的骨架packages/app-compat/src/firebaseNamespace.ts 的createFirebaseNamespace()在核心命名空间之上扩展出 INTERNAL 工具面namespace.INTERNAL { ...namespace.INTERNAL, createFirebaseNamespace, extendNamespace, createSubscribe, ErrorFactory, deepExtend };由于 auth 等组件无法与其他组件共享代码这些工具函数被挂到INTERNAL命名空间上供其他 compat 包复用——INTERNAL.extendNamespace(props)用deepExtend向顶层firebase命名空间注入新属性这正是各服务 compat 包寄生进 v8 全局 API 的机制。真正的工作量在 packages/app-compat/src/firebaseNamespaceCore.tsinitializeAppCompat(options, rawConfig)先调用模块化的modularAPIs.initializeApp()再检查同名 App 是否已缓存未命中则用new FirebaseAppImpl(app, namespace)包装后存入apps表。函数注释明确其为幂等idempotent同一 options/config 重复调用返回同一实例。app(name?)按名字取 App缺省为_DEFAULT_ENTRY_NAME即[DEFAULT]查无此 App 时抛出no-app错误。apps属性通过Object.defineProperty定义为只读 gettergetApps()返回拷贝数组防止外部篡改。registerComponentCompat(component)把组件名去掉-compat后缀若modularAPIs._registerComponent(component)成功且组件类型为ComponentType.PUBLIC则在命名空间上挂一个服务访问函数如firebase.firestore()参数非法既不是 App 也不是合法调用形式如firebase.storage(gs:/)时抛invalid-app-argument错误合并component.serviceProps到该函数对象上向FirebaseAppImpl原型打补丁生成app.firestore()这类实例方法并通过component.multipleInstances决定是否透传调用参数多实例服务如 storage、functions 会透传实例标识符。错误码定义在 packages/app-compat/src/errors.ts仅两个no-appNo Firebase App {appName} has been created - call Firebase App.initializeApp()与invalid-app-argument错误前缀为app-compat/Firebase。3.4 App 包装类与 Lite 变体packages/app-compat/src/firebaseApp.ts 中的FirebaseAppImpl是包装器范式的核心构造时通过_addComponent向底层 App 的ComponentContainer注册名为app-compat的 PUBLIC 组件使其他组件可反向拿到 compat Appname、options、automaticDataCollectionEnabled均为转发到_delegate模块化 App的 getter/setterdelete()先checkDestroyed()再调用this.firebase.INTERNAL.removeApp(this.name)从命名空间apps表移除最后deleteApp(this._delegate)级联销毁各服务_getService(name, instanceIdentifier)对InstantiationMode.EXPLICIT且尚未初始化的 provider 主动provider.initialize()再getImmediate({ identifier })取实例——这是firebase.app().storage(BUCKET ID)多实例能力的支撑_removeServiceInstance(name, instanceIdentifier)清除服务缓存以便重建注释说明目前仅 firestore shutdown 使用该能力。packages/app-compat/test/firebaseAppCompat.test.ts 对上述行为有逐项验证例如注册同名组件时服务命名空间保持不变幂等注册、返回缓存的服务实例、EXPLICIT 组件未被显式调用前消费方getImmediate({optional:true})得到 null、显式调用后会实例化、_removeServiceInstance后取到新实例且默认实例不受影响以及registerVersion对非法字符如remote config、1.2/3的告警行为。Lite 变体是独立 Performance 脚本场景的产物packages/app-compat/src/index.lite.ts 创建createFirebaseNamespaceLite()并以lite变体注册版本registerCoreComponents(lite)见 packages/app-compat/src/registerCoreComponents.tspackages/app-compat/src/lite/firebaseNamespaceLite.ts 把SDK_VERSION改写为${SDK_VERSION}_LITE这正是入口文件 LITE 探测的依据并将registerComponent收紧为registerComponentForLite仅允许 performance 与 installations 两个 PUBLIC 组件注册其余直接抛错packages/app-compat/src/lite/firebaseAppLite.ts 的FirebaseAppLiteImpl省略了container持有与 EXPLICIT 主动初始化逻辑_getService直接getImmediate。测试中 does NOT allow services other than Performance and installations to register 用例即验证该白名单。3.5 构建与测试脚本packages/app-compat/package.json 的 scripts 揭示了发布流程{ build: rollup -c yarn api-report, build:deps: lerna run build --scope firebase/app-compat --include-dependencies, test:all: vitest run, test:browser: vitest run --projectbrowser, test:node: vitest run --projectnode, api-report: api-extractor run --local --verbose, typings:public: node ../../scripts/build/use_typings.js ./dist/app-compat-public.d.ts }build由 rollup 产出 CJS/ESM/Lite 三种 bundle再跑api-extractor生成并比对 API 报告配置文件 packages/app-compat/api-extractor.json这保证了 0.1.0 以来 API 面的任何漂移都会在 CI 中被 API 报告发现——这也解释了为什么 0.3.x 之后该包几乎只有依赖联动版本API 契约被工具链锁得很死。typings:public用仓库脚本生成dist/app-compat-public.d.ts即 exports 中types条件指向的公开类型文件对应 0.1.27 的修复。测试以 vitest 双 projectnode/browser运行与 0.2.38/0.2.39 针对非标准全局环境Jest preset、Ionic Stencil的修复互为印证。4. 升级实践小结结合 CHANGELOG 与源码给依赖firebase主包间接使用firebase/app-compat的项目几条可操作结论API 面极其稳定0.1.0 之后除构建/构建目标/依赖外无破坏性 API 变更initializeApp/app/apps/registerVersion/setLogLevel/onLog/SDK_VERSION等命名空间成员定义在 packages/app-compat/src/public-types.ts 的FirebaseNamespace接口中。运行环境边界在持续上移产物 ES 目标 ES5 → ES20170.2.44→ ES20200.5.0仓库内构建/测试要求 Node 从 200.5.0 起进一步上调至当前 package.json 声明的24.12.0。默认值变更以 0.4.0 为准automaticDataCollectionEnabled默认 true 的变更经历 0.3.0 提出、0.3.1 回滚、0.4.0 重新落地且明确不改变 App Check 的默认行为。全局重复加载告警若控制台出现 Firebase is already defined in the global scope 或 Performance standalone 相关告警对应的是 入口检测逻辑应检查是否同时引入了firebase主包与独立 Performance 脚本。INTERNAL面不属于公开 APIregisterComponent、extendNamespace等仅供仓库内各 compat 包组装使用业务代码不应依赖官方 README 亦声明本包只应经由firebase包使用。5. 参考资料仓库内路径packages/app-compat/CHANGELOG.md —— 本文主线完整版本历史packages/app-compat/README.md —— 包定位说明packages/app-compat/package.json —— exports/engines/依赖与构建脚本packages/app-compat/src/index.ts、src/firebaseNamespace.ts、src/firebaseNamespaceCore.ts —— 命名空间构建与组件注册packages/app-compat/src/firebaseApp.ts、src/errors.ts、src/public-types.ts —— App 包装、错误码与公开类型packages/app-compat/src/lite/firebaseNamespaceLite.ts、src/lite/firebaseAppLite.ts、src/index.lite.ts —— Lite 变体packages/app-compat/test/firebaseAppCompat.test.ts —— 注册、缓存、多实例、版本注册等行为验证赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐Firebase AI Logic SDKFirebaseAI演进全解析从模块重命名到 Gemini Live API 的版本变迁指南Firebase AI Logic SDKFirebaseAI演进全解析从模块重命名到 Gemini Live API 的版本变迁指南 本篇技术指南以开源移动开发后端React Native Firebase App Check 模块演进全解析从首次引入到 TurboModule 与 firebase-js-sdk 类型对齐v12.5 – v26.4React Native Firebase App Check 模块演进全解析从首次引入到 TurboModule 与 firebase js sdk 类型对移动开发后端Medusa 模块 SDK 深度解析从 MedusaApp 到模块化架构的演进与实践Medusa 模块 SDK 深度解析从 MedusaApp 到模块化架构的演进与实践 medusajs/modules sdk 是 Medusa 平台模块化后端电商前端上一篇LobeHub 1.x 升级到 2.0 需要处理哪些破坏性变更下一篇FLASH-MD 多设备设置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考