@gideo-llc/backblaze-b2-upload-any

中文文档
0.1.5发布于 2026/02/06MITCommonJS近 30 天下载 2185

与后燃- b2 模块一起使用的智能上传功能

中文使用文档
文档目录9 节
  1. 快开始
  2. 无侵犯性
  3. 侵入性
  4. 特性介绍
  5. 上传令牌管理
  6. 流上传
  7. 自动大文件上传
  8. API 密码
  9. 上传任何( 选项)

@gideo-llc/backflaze-b2-upload- any (英语)

智能上传功能,用于其中 后发-b2 模块。 此函数可以上传缓冲、流和本地文件,并自动使用 B2 的 大文件上传 酌情建立机制.

  • 上传令牌管理 : 维护一桶可以再用于未来请求的已使用上传符,允许大量简化的平行上传而无需手动管理上传符.
  • 智能自动重试 : 如果目标舱忙于接收上传,在获得新的上传令牌后会自动被重审. 相继出错会导致指数倒置. 这个 retry-after HTTP 响应头被尊重 .
  • 自动重授权 : 401出错会导致自动再授权. 被中断的上传将透明地重试 .
  • 串流支持 : 上传的文件可以作为流提供.
  • 文件支持 : 磁盘上的文件可以上传. 此例具有独特的优化, 无法用流对象进行 .
  • 自动大文件上传 : 如果上传的数据大于指定的阈值,则会使用B2的大文件API自动被上传到多块中. (当数据以流提供时,流中的某些部分可能会被缓冲入内存. 这对于便于在信使过期时进行再审是必要的。 )

快开始

无侵犯性

const B2 = require('backblaze-b2');

B2.prototype.uploadAny = require('@gideo-llc/backblaze-b2-upload-any');

const b2 = new B2({
    applicationKeyId: '...',
    applicationKey: '...',
});

b2.authorize()
.then(r =>
    b2.uploadAny({
        bucketId: '...',
        fileName: 'foo',
        partSize: r.data.recommendedPartSize,
        data: /* buffer, stream, or file path */,
    })
)
.then(() => { console.log('Upload complete'); }, console.log);

侵入性

一个 install 函数导出。 当使用 B2 构造器功能被调用时,它将在其原型上安装两个包装:

  • authorize 被包裹起来。 从响应中提取出推荐的部分大小,并与B2客户对象相关.
  • uploadAny 被包裹起来。 选项对象的默认值 partSize 属性设置为建议小于 authorize 发现包裹.

这简化了正确使用 uploadAny 函数,因为推荐的部件大小无需绕行您的应用程序.

const B2 = require('backblaze-b2');

require('@gideo-llc/backblaze-b2-upload-any').install(B2);

const b2 = new B2({
    applicationKeyId: '...',
    applicationKey: '...',
});

b2.authorize()
.then(() =>
    b2.uploadAny({
        bucketId: '...',
        fileName: 'foo',
        data: /* buffer, stream, or file path */,
    })
)
.then(() => { console.log('Upload complete'); }, console.log);

特性介绍

上传令牌管理

B2需要针对每个同时上传请求分别提供上传URL和授权令牌;重用当前被未解决请求使用的令牌将返回400个错误. 此外,一个符号可能随时会停止工作,服务器会发出503个错误的信号.

此函数通过采取任何适当的动作并重试失败的请求,自动处理这些预期的失败情景.

在引擎盖下,每个桶都有上传URL/token对和每个未完成的大文件上传的队列. 当一个新的上传请求开始时,会从这个缓冲器中去掉一个令牌(或者如果队列是空的会获得一个新的令牌). 当请求成功完成时,该请求所用的符号被排列,以便未来的请求可以再使用. 如果上传请求因舱位太繁忙而失败,则该令牌被丢弃,并在从队列中获取了另一个令牌(或者如果队列是空的,则从B2中获取)后重新测试请求.

使用此机制, 令牌池会自动增大, 以满足您的应用的货币需求 .

流上传

上传文件时,数据可以作为流提供. 上传功能的使用在使用流时完全相同.

由于上传请求由于繁忙的吊舱而经常需要重审,一些流数据可能在内存中被缓冲. 详见下一节.

自动大文件上传

如果来自任何来源的上传(流,缓冲,或文件)大于B2推荐的"大文件"阈值,客户端将自动使用大文件API来将内容上传成片. 这一过程对呼叫者来说是透明的.

如果源是一个流,请注意大文件上传的部分必须被保存在内存中,以便于当一个吊舱太忙时进行重试. (在上传缓冲器时,此库不会分配额外的缓冲;在上传由本地路径指定的文件时,内容会被直接流到服务器. )

以下属性用于控制大文件上传的方面:

  • concurrency: 同时上传要执行的部分的数目。 默认为 1 .
  • largeFileThreshold: 使用大文件API所需的大小(以字节计). 小于此的文件在单个中上传 b2_upload_file 请求.
  • partSize:每个上传部分的大小(以字节计). B2允许部分大小在5MB到5GB之间. B2 返回的推荐部件大小默认值 authorize API电话. (注意这一数值与B2文件中的建议相同 -- -- 目前为100MB。) 如果您将执行许多并行流上传或设置 concurrency 相当高, 考虑指定更小的值来避免在 JavaScript 堆积中耗尽可用的内存

注意B2只接受最多一万个部件的单个文件. 若为 contentLength / partSize > 10000 然后上传最终会失败.

API 密码

此模块导出单个函数 uploadAny,必须用 B2 对象作为上下文。 此功能可附在原型 backblaze-b2 客户端.

上传任何( 选项)

根据指定的选项上传新文件. options 为具有下列属性的对象:

  • bucketId: 字符串, 需要 。 要上传的桶ID .
  • concurrency: 数. 同步上传可以同时执行的部分的数量. 只用于大文件模式 。 默认为 1 .
  • contentType:弦乐. B2对象上记录的MIME类型. 默认为 b2/x-auto。 。 。 .
  • data:缓冲,可读流,或作弦. 要求.
    • 如果缓冲器,缓冲器的全部内容会被上传. 用缓冲器 .subarray() 方法,如果缓冲器的分节应当上传.
    • 如果一个可读流,生成的所有数据都会被上传. 流不能以对象模式存在 .
    • 如果一个字符串,则该字符串命名的本地文件会被上传. (要上传字符串的内容,请使用 Buffer.from(string, encoding) 函数。)
  • fileName: 字符串, 需要 。 在 B2 中创建对象的名称 .
  • largeFileThreshold: 数. 启用大文件模式的字节大小 。 一定超过 partSize默认为 partSize * 2。 。 。 .
  • partSize: 数目,需要。 以字节上传每个部分的大小 。 只用于大文件模式 。 一定在500万(5MB)到5000万(5GB)之间.

返回对 JSON 解码反应机构的许诺 b2_upload_file 或者说 b2_finish_large_file API呼叫,取决于使用哪种机制.

版本与发布记录

@gideo-llc/backblaze-b2-upload-any 共发布 9 个版本,首次发布于 2020/02/19;过去 12 个月发布了 1 个版本。

版本发布日期距今
0.1.5latest2026/02/069 个月前
0.1.42021/05/255 年前
0.1.32020/02/286 年前
0.1.22020/02/246 年前
0.1.12020/02/226 年前
0.1.02020/02/226 年前

关于 @gideo-llc/backblaze-b2-upload-any 的常见问题

@gideo-llc/backblaze-b2-upload-any 是什么?

与后燃- b2 模块一起使用的智能上传功能

如何安装 @gideo-llc/backblaze-b2-upload-any?

在项目目录运行 npm install @gideo-llc/backblaze-b2-upload-any,或使用 pnpm add / yarn add / bun add。

@gideo-llc/backblaze-b2-upload-any 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gideo-llc__backblaze-b2-upload-any 是否存在。

@gideo-llc/backblaze-b2-upload-any 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gideo-llc/backblaze-b2-upload-any 可以商用吗?

@gideo-llc/backblaze-b2-upload-any 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gideo-llc/backblaze-b2-upload-any 的下载量有多少?

根据 npm 官方下载统计,@gideo-llc/backblaze-b2-upload-any 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,185 次,日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gideo-llc/backblaze-b2-upload-any 还在维护吗?

最新版本 0.1.5 发布于 2026/02/06(9 个月前);至今共发布 9 个版本,其中过去 12 个月发布了 1 个;首次发布于 2020/02/19。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。