# @gideo-llc/backblaze-b2-upload-any 中文文档

规范地址：https://npmcn.com/package/%40gideo-llc/backblaze-b2-upload-any/

版本：0\.1\.5
npm 元数据更新时间：2026-02-05T22:25:27.962Z
中文译文更新时间：2026-11-16T13:24:57.494Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gideo-llc/backblaze-b2-upload-any
原文对照：https://npmcn.com/package/%40gideo-llc/backblaze-b2-upload-any/?lang=original
项目主页：https://github.com/gideo-llc/backblaze-b2-upload-any#readme
源码仓库：https://github.com/gideo-llc/backblaze-b2-upload-any

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：43.7 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2020-02-18T21:14:43.670Z
- 最新版本发布：2026-02-05T22:25:27.834Z
- 近 30 天下载量：2185（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 1 个）

## 中文简介

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

## 安装

```sh
npm install @gideo-llc/backblaze-b2-upload-any
```

也可以使用：`pnpm add @gideo-llc/backblaze-b2-upload-any`、`yarn add @gideo-llc/backblaze-b2-upload-any`、`bun add @gideo-llc/backblaze-b2-upload-any`

## README

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

智能上传功能,用于其中 [后发-b2](https://www.npmjs.com/package/backblaze-b2) 模块。 此函数可以上传缓冲、流和本地文件,并自动使用 B2 的 [大文件上传](https://www.backblaze.com/b2/docs/large_files.html) 酌情建立机制.

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

## 快开始

### 无侵犯性

```js
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` 函数,因为推荐的部件大小无需绕行您的应用程序.

```js
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 是什么？

与后燃- 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 和提交记录判断。

