★ FEATURED ARTICLE 开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载导读firebase/storage-types是 Firebase JS SDK 中专门承载 Cloud Storage 公共 TypeScript 类型声明的纯类型包其 CHANGELOG.md 记录了从 0.3.13 到 0.8.5 的完整版本演进。本文以这份变更日志为线索结合同仓库的 index.d.ts、public-types.ts 与测试用例逐条还原每个版本背后的真实代码变更——包括useEmulator/connectStorageEmulator模拟器支持、mockUserToken安全规则测试令牌、StorageError实例判断修复、TypeScript 升级等帮助读者既看清改了什么也明白为什么改、底层怎么实现。注意根据 README.md本包不面向直接使用仅应通过官方firebase包间接使用当前仓库中它作为firebase/storage-compat的 peer 依赖存在见 storage-compat/package.json。一、这个包是什么纯类型包与版本演进全貌firebase/storage-types的发布物只有一个文件index.d.ts见 package.json它只导出类型、不包含任何运行时逻辑作用是为 Firebase Storage 的公共 API 提供稳定的 TypeScript 契约。其 peer 依赖为firebase/app-types0.x与firebase/util1.xpackage.json说明类型定义依赖 app 与 util 两个基础包的类型。从 CHANGELOG 可以梳理出这条清晰的时间线版本类型核心变更0.3.13Patch允许 Observer 类 API 省略回调修复 #32240.4.0Minor新增storage().useEmulator()模拟器方法PR #43460.4.1Patch更新 peerDependencies修复 #47890.5.0Minor实现 Storage 的mockUserToken并修复 JWT 格式问题PR #52820.6.0Minor发布模块化 SDKPR #5345修复 #50150.6.1 / 0.7.0Patch/MinorTypeScript 升级至 4.7.4PR #6682 / #67990.8.0Minor修复用户无法用instanceof StorageError判断错误的问题PR #69740.8.1Patch统一各包repository.url为 NPM 偏好格式PR #80790.8.2Patch全包 bump 以配合 staging 流程PR #82370.8.3PatchTypeScript 升级至 5.5.4PR #86040.8.4 / 0.8.5Patch更新依赖与顶层 devDependenciesPR #9883 / #10293可以看到这个类型包的版本演进与整个 SDK 的架构转型模块化、工程基建TypeScript 版本、依赖管理以及模拟器生态emulator、mock token高度同步。二、0.3.13Observer 回调全部可省略0.3.13 的变更PR #3224是为所有使用 Observer 的 API 更新 TypeScript 类型允许省略回调。这对应 index.d.ts 中的StorageObserverTexport interface StorageObserverT { next?: NextFnT | null; error?: (error: FirebaseStorageError) void | null; complete?: CompleteFn | null; }三个回调全部是可选的?配合UploadTask.on()的签名index.d.ts开发者可以只监听完成、只监听进度甚至先拿到订阅函数再延迟注册回调。这正是 Firebase Storage 上传任务观察者模式的典型用法next观察进度、error处理失败、complete收尾三者互不依赖。三、0.4.0useEmulator()方法加入类型契约0.4.0PR #4346为 Storage 增加了模拟器支持对应 index.d.ts 中FirebaseStorage类上的useEmulator方法useEmulator( host: string, port: number, options?: { mockUserToken?: EmulatorMockTokenOptions | string; } ): void;在模块化 SDK 中这个能力由 api.ts 导出的connectStorageEmulator(storage, host, port, options)提供useEmulator是 compat 层对它的封装。其底层实现位于 service.ts 的connectStorageEmulator函数export function connectStorageEmulator( storage: FirebaseStorageImpl, host: string, port: number, options: { mockUserToken?: EmulatorMockTokenOptions | string } {} ): void { storage.host ${host}:${port}; const useSsl isCloudWorkstation(host); if (useSsl) { void pingServer(https://${storage.host}/b).catch(() {}); } storage._isUsingEmulator true; storage._protocol useSsl ? https : http; const { mockUserToken } options; if (mockUserToken) { storage._overrideAuthToken typeof mockUserToken string ? mockUserToken : createMockUserToken(mockUserToken, storage.app.options.projectId); } }几个值得注意的实现细节主机拼接把默认主机firebasestorage.googleapis.comconstants.ts替换为host:port所有后续请求都指向模拟器协议自适应普通 localhost 走http若是 Cloud Workstations 环境isCloudWorkstation则强制https并附带一个 cookie 预热请求这是针对 Firebase Studio 等环境的特殊处理令牌注入传入mockUserToken时写入_overrideAuthToken后续请求头Authorization: Firebase token将使用该令牌自动连接getStorage()内部还会调用getDefaultEmulatorHostnameAndPort(storage)一旦检测到环境变量配置的模拟器地址就自动连接api.ts。单元测试 service.test.ts 验证了这些行为设置localhost:1234后host变为localhost:1234、协议为http、请求 URL 匹配http://localhost:1234/...而传入test.cloudworkstations.dev时协议变为https。四、0.5.0mockUserToken与 JWT 格式修复0.5.0PR #5282实现了 Storage 的mockUserToken并修复了 JWT 格式问题。mockUserToken的用途是在单元测试中模拟一个已认证用户从而测试 Security Rules。它接受两种形式字符串形式直接作为令牌使用typeof mockUserToken string分支对象形式交给createMockUserToken(mockUserToken, projectId)生成一个无签名的 JWTalg: none。对象形式的具体构造逻辑在 emulator.ts使用sub或user_id字段作为用户 ID默认填充iss、aud、expiat 3600、firebase.sign_in_provider: custom等字段再以 base64url 编码的 header/payload 拼接空签名。同时该实现会拒绝已废弃的uid字段并抛出明确提示——这也是 CHANGELOG 中所说修复 JWT 格式问题的一部分。类型定义EmulatorMockTokenOptions为({ user_id: string } | { sub: string }) PartialFirebaseIdTokenemulator.ts并明确uid?: never以在编译期拦截误用。测试用例验证了两种形式的效果字符串令牌直接出现在Authorization: Firebase token请求头中对象形式如{ sub: alice }生成的令牌以eyJhbGciOiJub25lIiwidHlwZSI6IkpXVCJ9.开头正是{ alg: none, type: JWT }的 base64url 编码service.test.ts。五、0.6.0模块化 SDK 与类型包的分工0.6.0PR #5345修复 #5015标志着 SDK 全面模块化。在此之前firebase/storage-types承载的是兼容层compatAPI 的类型模块化之后新一代的公开类型定义迁移到了主包 public-types.ts包含StorageReference、ListOptions、UploadTask、StorageObserver、FullMetadata等而firebase/storage-types继续为 compat 层提供兼容类型契约并在 index.d.ts 中通过declare module firebase/component将storage-compat服务注册进组件依赖注入映射。这一阶段还体现出一个细节虽然主包已模块化useEmulator等旧 API 名称仍保留在类型包中保证从旧版迁移到新版例如把firebase.storage().useEmulator(...)换成connectStorageEmulator(storage, ...)时有类型可循、迁移成本可控。六、0.8.0StorageError的 instanceof 判断修复0.8.0PR #6974修复 #6944修复了用户无法用instanceof StorageError判断错误实例的问题。这是 JavaScript 继承机制的一个经典陷阱StorageError继承自FirebaseError当 TypeScript 编译目标把类编译成 ES5 风格的构造函数时instanceof可能失效。修复方法直接体现在 error.ts 的构造函数中constructor( code: StorageErrorCode, message: string, private status_ 0 ) { super( prependCode(code), Firebase Storage: ${message} (${prependCode(code)}) ); this._baseMessage this.message; // Without this, instanceof StorageError, in tests for example, // returns false. Object.setPrototypeOf(this, StorageError.prototype); }Object.setPrototypeOf(this, StorageError.prototype)显式修正原型链使err instanceof StorageError恢复正确结果。同时StorageError对外暴露了code带storage/前缀的错误码prependCode(code)生成见 error.tscustomData.serverResponse服务端返回的原始响应文本status对应的 HTTP 状态码_codeEquals(code)忽略前缀地比较错误码。类型包侧则对应 index.d.ts 的StorageErrorCode枚举与FirebaseStorageError接口。StorageErrorCode枚举共 24 个错误码覆盖了共享错误unknown、object-not-found、bucket-not-found、quota-exceeded、unauthorized等与 JS 特有错误invalid-url、invalid-format、no-default-bucket、cannot-slice-blob、server-file-wrong-size、unsupported-environment等这些枚举值也在 error.ts 中一一对应实现。七、工程基建类变更TypeScript 版本与依赖管理CHANGELOG 后半段的多次 Patch 变更集中在工程基建上0.6.1 / 0.7.0PR #6682 / #6799TypeScript 升级至 4.7.40.8.1PR #8079统一所有包package.json的repository.url为 NPM 偏好的格式0.8.2PR #8237全包 bump 以配合 staging 发布流程0.8.3PR #8604TypeScript 升级至 5.5.4当前 package.json 中devDependencies.typescript即为5.5.40.8.4 / 0.8.5PR #9883 / #10293更新依赖与顶层 devDependencies。由于类型包自身的测试就是tsc类型检查package.json 中test: tscTypeScript 版本升级直接影响类型声明的正确性与兼容性——这也解释了为什么类型包会如此频繁地跟随 TS 主版本升级。对于开发者而言这些变更的意义在于使用新版 TypeScript 编译自己的项目时firebase/storage-types的类型定义能够保持兼容不会因编译目标差异产生类型错误。八、类型契约速览这份.d.ts到底定义了哪些 API把 index.d.ts 当作一份接口地图Storage 类型包的核心类型可以归纳如下类型关键字段 / 方法用途FirebaseStorageref()、refFromURL()、setMaxOperationRetryTime()、setMaxUploadRetryTime()、useEmulator()Storage 服务实例Referencechild()、put()、putString()、getDownloadURL()、getMetadata()、updateMetadata()、delete()、list()、listAll()对象/路径引用UploadTaskon()、pause()、resume()、cancel()、then()、catch()、snapshot可观察的上传任务UploadTaskSnapshotbytesTransferred、totalBytes、state、ref、metadata上传进度快照SettableMetadatacacheControl、contentType、contentLanguage、customMetadata等可写元数据UploadMetadata继承SettableMetadata追加md5Hash上传元数据FullMetadata继承UploadMetadata追加bucket、generation、size、downloadTokens等完整元数据ListOptions/ListResultmaxResults、pageToken/prefixes、items、nextPageToken目录列举StorageErrorCode24 个storage/*错误码错误分类值得注意的默认值与上限ListOptions.maxResults的默认和最大值都是 1000见 public-types.ts 的文档注释setMaxOperationRetryTime与setMaxUploadRetryTime的默认值分别是 2 分钟与 10 分钟constants.ts。理解这些类型契约无论做二次封装、编写类型安全的业务代码还是排查类型报错都有直接的帮助。结语firebase/storage-types的 CHANGELOG 看起来只是几十行版本记录但每一条都对应着真实的功能演进Observer 类型从严格到宽松的 API 设计、模拟器接入从无到有、mockUserToken从实现到 JWT 格式修正、StorageError原型链修复以及 TypeScript 与依赖基建的持续跟进。透过类型包的视角可以清晰地看到 Firebase JS SDK 如何在保持 API 兼容的同时持续打磨类型安全与开发体验。若想深入探索推荐继续阅读 public-types.ts模块化公开类型、service.ts服务与模拟器实现和 error.ts错误模型并结合 service.test.ts 中的单元测试理解各项行为的验证方式。赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐Wand-Enhancer 完全指南三分钟本地补丁免费解锁 Wand 订阅功能Wand Enhancer 完全指南三分钟本地补丁免费解锁 Wand 订阅功能 Wand原 WeMod免费版每天只给两小时额度倒计时一归零修改器直接开发工具后端firebase-js-sdk firebase/firestore 变更日志深度解读从 0.1.0 到 4.18.0 的版本演进与关键特性追踪firebase js sdk firebase/firestore 变更日志深度解读从 0.1.0 到 4.18.0 的版本演进与关键特性追踪 fire开发工具后端Cloud Storage for Firebase JS SDK从 firebase/storage 版本演进看核心能力与实现原理Cloud Storage for Firebase JS SDK从 firebase/storage 版本演进看核心能力与实现原理 本文以 firebas开发工具后端上一篇Qwen1.5-1.8B-Chat-GPTQ-Int8与其他模型对比分析终极性能评测指南下一篇EveryDay 中的 CSS 布局秘籍Flex、Grid 与响应式设计全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
