# @cloudbitmaps/s3 中文文档

规范地址：https://npmcn.com/package/%40cloudbitmaps/s3/

版本：0\.27\.0
npm 元数据更新时间：2026-11-03T05:51:33.394Z
中文译文更新时间：2026-11-10T04:18:52.302Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudbitmaps/s3
原文对照：https://npmcn.com/package/%40cloudbitmaps/s3/?lang=original
项目主页：https://github.com/cloudbitmaps/cloudbitmaps#readme
源码仓库：https://github.com/cloudbitmaps/cloudbitmaps

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

- 包体积（解压后）：272 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：2 个
- 首次发布：2026-09-22T02:44:47.559Z
- 最新版本发布：2026-11-03T05:51:32.971Z
- 近 30 天下载量：2388（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

S3和S3兼容存储 (R2, Minio, Ceph, Wasabi, B2) 用于 CloudBitmaps

## 安装

```sh
npm install @cloudbitmaps/s3
```

也可以使用：`pnpm add @cloudbitmaps/s3`、`yarn add @cloudbitmaps/s3`、`bun add @cloudbitmaps/s3`

## README

# @ cloudbitmaps/ s3 图像

**S3 存储 [云位图](https://github.com/cloudbitmaps/cloudbitmaps)。 。 。 .** 一桶握住你世代和他们的指针 所以没有第二 服务运行.

> **仅限无害环境管理,节点22.12.** 使用 `import`; 用于 `require()`时标和类型脚本,参见 [常见的JS、快取和类型脚本](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#commonjs-jest-and-typescript)。 。 。 .

> 前1.0:API和上盘格式仍然可以更改. 在npm上,这些文件与它们所运送的版本相符;在GitHub上,它们描述 `main`,更改日志则说每个版本都改变了什么.

## 安装

```bash
pnpm add @cloudbitmaps/roaring @cloudbitmaps/s3
```

安装每张的同版本 `@cloudbitmaps/*` 软件包:它们一起发行,每个包都标出准确的版本 `core` 它是与建造的.

`@aws-sdk/client-s3` (单位:千美元)`>=3.700.0 <4`)是这个包的真正依赖性,所以安装是整个步骤. 新鲜的安装可以解析到最新的 3.x 发布, 除非锁文件把它接上: 从锁文件安装, 运行 `npm audit signatures`检查一下SDK起落架. `@cloudbitmaps/core`引擎在下面,随它而来,而你却不给它起名.

## 使用

```ts
import { CloudRoaring } from '@cloudbitmaps/roaring';
import { S3Storage } from '@cloudbitmaps/s3';

const store = new CloudRoaring({
  storage: new S3Storage({ bucket: 'bitmaps', prefix: 'cr', region: 'us-east-1' }),
});

await store.load({ segment: 'active-users' }, [1, 2, 3]);
await store.segment('active-users').has(2); // true
```

它从你通常的AWS证书中构建了自己的客户端. 任何其他密钥都会被姓名拒绝.

| 选项 | 它会做什么 |
| --- | --- |
| `bucket` (必须) | 桶头 |
| `prefix` | 此商店所写每件事的密钥前缀 |
| `client` | 你们自己 `S3Client`它携带自己的区域、终点和证书 |
| `region`, (中文(简体) ), `endpoint`, (中文(简体) ), `pathStyle`, (中文(简体) ), `credentials` | 为您创建客户端, 例如为 MinIO 创建客户端; 拒绝 `client` |
| `maxSockets` | 大部分套接字您不会马上通过客户端打开, 因为 `https` 简单 `http` 相同; 正整数, 默认为 128( SDK 的自有为 50; 如果未来的 SDK 更改了它的处理器, 已建客户端保留 SDK 的自有限制 ); 被拒绝 `client` |
| `partBytes`, (中文(简体) ), `maxObjectBytes` | 多分大小:部分大小(默认为8 MiB;上传缓冲器一次分出一个部分并复制到一个正体中以发送,因此在一冲上可以维持约两倍分大小,默认为16 MiB,取自驱动程序代码)和最大对象(默认为约78 GiB,可达S3's 5 TiB). 5 TiB以上的上限,或S3的5 GiB部分限制以上的部分,是 `ValidationError` |
| `readTimeoutMs` | 读取时间(a) `GetObject` 或者说 `HeadObject`,包括身体在内)在投出前可能取出 `TransientError` 和店铺重试它; `0`,默认值,不设置超时值。 写作没有定时 |
| `conditionalDelete` | 商店是否适用 `If-Match` 编号 `DeleteObject`:然后登记簿去掉被删除的行而不是留下墓碑,而存储半则只删除了被删除对象时所读取的已删除的被删除对象,由它的ETag. 默认情况下,当主机解析客户端为 AWS S3 主机时,尽管其端点已经设定(`endpoint`, (中文(简体) ), `AWS_ENDPOINT_URL_S3`, (中文(简体) ), `AWS_ENDPOINT_URL`,共享配置文件; 关闭用于其他主机: 仅在您知道S3兼容的商店应用了信头( MinIO 忽略它) 时将其设定为该商店 |

## 生产前

-   **运行 `await store.preflight()` 第一次载货之前.** 它读登记册,写一个探测器,写下 同样的密钥(必须拒绝),读回来,列出,删除,检查生命周期规则,与 `s3:ListBucket`, (中文(简体) ), `s3:GetObject`, (中文(简体) ), `s3:PutObject` 财务报告和审定财务报表 `s3:DeleteObject`,以及 `s3:GetLifecycleConfiguration` 最后一个 没错 未检查 `s3:AbortMultipartUpload`,登记簿的 `If-Match`,或删除后读取,除其他外: [完整列表](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#what-preflight-does-not-check)。 显示3.640.0或以上的SDK为 `write-once` 问题,不能看到一个 从3.641.0到3.699.0, 所以下面的地板留你检查。 探测器坐落在 `<prefix>cbm.due.preflight/`,在您的应用程序命名空间之外:每个命名空间显示的赠款范围 `write` 问题,作为一个 `registry` 登记处的拨款是否为每个命名空间的范围也有问题.
-   **水桶必须尊重有条件的写法**数字 : `If-None-Match: *` 为一代人而写作 `If-Match` 联 合 国 指针. AWS S3确实如此,测试套件运行于MinIO. 另一个忽略信头的S3兼容服务 将写入封面, 在依赖它之前先检查你的。 还必须坚决保持一致: 或写入或删除返回后列出的条目。 AWS S3为.
-   **使用 `@aws-sdk/client-s3` 3.700.00 或以后时间** 如果你把SDK扣上或者通过自己的 `client`。这层楼是 正确性底线,而不是偏好。 SDK只发送其模型的有条件信头,并丢掉它做的一个 不,没有错误. `If-None-Match`以 3.641.0 为模型: MinIO, 3.640.0 沉默地覆盖一个已存在的对象,它失去了一个已公布的一代. `If-Match` 打开 `PutObject`以3.700:3.699.0的序列器为模型 省略它,所以一个有栅栏的行 写出无条件 并且可以降落在一个同时的作家。 这个包裹 自有范围从不解决低于3.700.0。 登记处在首次提出请求之前,还检查其获得的客户是否发送 `If-None-Match` 财务报告和审定财务报表 `If-Match` 打开 `PutObject`,拒绝不附带先决条件地发送的注册 未发送 `If-Match` 打开 `DeleteObject` 转弯 `conditionalDelete` 从3.723.0开始,SDK发送了2个米B或更多的一部分 (单位:千美元)`Expect: 100-continue`)在外接线上 `maxSockets`在它之前,上传者共用游泳池 上限也限制了它们(预期的,没有测量的:低上限的上传率较低,没有更糟糕的了).
-   **赠款 `s3:GetObject`, (中文(简体) ), `s3:PutObject`, (中文(简体) ), `s3:DeleteObject`, (中文(简体) ), `s3:AbortMultipartUpload` 财务报告和审定财务报表 `s3:ListBucket`。 。 。 .** 无 `s3:ListBucket`, S3 以 `403` 改为 `404`。 。 。 .
-   **添加终止不完整多段上传的生命周期规则**中,从不终止当前对象或 `registry/` 前缀。 过期的注册行将部分的指针用它取出,每一份出版物都用栅栏表示 因此,它的世代看起来没有参考; 过期的一代使得一个活段无法读取 (单位:千美元)[桶生命周期](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#bucket-lifecycle)) (中文(简体) ).
-   **检查桶的生命周期规则 `await backend.checkLifecycle()`。 。 。 .** 它读一个配置 请求 `readTimeoutMs`和答案 `ok`, (中文(简体) ), `problem` (对于过期当前对象或移动的您前缀, 一个启用的, 未标记的规则) 他们去 `GLACIER`, (中文(简体) ), `DEEP_ARCHIVE` 或它不知道的类别)或 `unchecked`它需要 `s3:GetLifecycleConfiguration`,负载从不使用 `store.preflight()`'生命周期步骤确实如此:没有它,答案就是 `unchecked`,命名权限。 缺失的中止- 不完整上载规则是 咨询意见 `detail`从来没有 `problem` (单位:千美元)[从代码中检查生命周期规则](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#check-the-lifecycle-rules-from-code)) (中文(简体) ).
-   **写作的瞬间失败 `TransientError`,而写作可能已经着陆,也可能没有着陆.** 重开电话, 或检查 `store.generations(ref)`。SDK自己的重试取消了,用于有条件的写作,所以登陆的写作不是 报告为冲突。 驾驶员 [发送每个注册文件 一次](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#sdk-retry); 负载得到否 回复 [读取行并发送新的比较和扫描 这个](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#row-write-settled),最多3个 时间。 一代人的对象被再次发送,最多再发送三次,只有在一个之后 `503` (单位:千美元)`SlowDown` 或赤裸裸的 `429` (单位:千美元)[为什么是 保险](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#object-write-resent)(三); 它在它的用户元数据中带有随机的id(`x-amz-meta-cbwid`),所以第一个登陆的发件人从另一个发件人那里得知 作家对象. 排行写字的负载都会被解答 `TransientError` 并保持它的对象。 等待着 在对象的再发送使用实时计时器之前:商店的注入时钟没有到达它们,以及 `S3Storage` 采取不 时钟,所以一个测试 节流器一个物体写出三次 最多等待3.5秒左右( 出版者等待 a) 新鲜行写确实使用商店的时钟). **一个赤裸的 `429`** (AWS S3不发送一个;一些S3兼容的服务是) **是一个油门,处理得就像一个 `503` 实值**一个结束一个呼叫是 `TransientError`。 。 。 .
-   **阅读可以被定时,而写作不是.** 没有时间,除非你设定 `readTimeoutMs`设置,一个读取有 未完成于许多 ms 抛出 `TransientError`,然后商店再次运行它; AWS 的指导是重试一个 GET 512 KB以下 大约2秒后 计时器也覆盖着身体 所以一个连接 发送它的头和 然后摊子也被切断了。 当读数被交给SDK时,它就开始了, 所以一个爆发的读数大于 已建客户端的套接字池( 默认为 128) 可在队列时超时: 将其设置在队列上方, 或加高 `maxSockets` 联合国 `client` 你通过它自己的游泳池. 对于写作和列表,给您的客户一个自己的超时.

这个 [生产清单](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md) 包含每个项目, 以及每个后端共享的 IAM 政策样本 : 请求程序库没有时间的客户端请求超时, 数据备份和注册, 以及您负载的时间表 .

-   **驾驶员在丢弃前会校正其识别出的错误的证书 .** AWS SDK 保留 它在错误上得到的响应 (`$response`),并通过套接字发送请求,并附有签名 `Authorization` 页眉和 `x-amz-security-token`。它也会将错误主体的每个字段都放在错误上, S3 回引拒绝时的请求:其签名和方言请求(`SignatureDoesNotMatch`),或该词 会话符号( c)`Token-0`打开 `ExpiredToken` 财务报告和审定财务报表 `InvalidToken`) (中文(简体) ). 在驱动程序抛出的错误中, a 下的值 证书页眉或字段名称被替换为 `[redacted]` (单位:千美元)`authorization`, (中文(简体) ), `x-amz-security-token`, (中文(简体) ), `x-amz-s3session-token`一个SSE -C键, `SignatureProvided`, (中文(简体) ), `CanonicalRequest`, (中文(简体) ), `Token-0` 和同类 密钥 id S3 名称被保留),在列表或记录(一个表格行 解析为 `{ th, td }` 一个名称和一个值, a `{ name, value }` 双人, `ArgumentName` 财务报告和审定财务报表 `ArgumentValue`),一个证书头行,一个SigV4签名 (单位:千美元)`Signature=`, (中文(简体) ), `X-Amz-Signature=`)和会话符号或SSE-C密钥,取自其标题后,文本中任意位置。 A 类 另一种形式的证书不被承认,而对于这些图案来说,一个太大的文本被替换为整体。 一个SDK 载运或显示证书的错误,以及它所到达的每一个错误 `cause` 链条, a `AggregateError`是因为 `errors`),被抛出为复制:一个原型,名称,消息,堆栈, `$metadata`, (中文(简体) ), `$fault`, (中文(简体) ), `Code` 所以分类没有变化 没有 `$response`尸体是SDK的 无法解析( c)`$responseBodyText`),任何功能或存取器属性,或任何被巢于十级以下的东西. 活出错误是永远不变的,一个没有运输能力、没有证书的错误被抛出.

## 文档

-   [开始](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md)
-   [生产前](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md)
-   [API 参考](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/api-reference.md)
-   [更改日志](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/CHANGELOG.md)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @cloudbitmaps/s3 是什么？

S3和S3兼容存储 \(R2, Minio, Ceph, Wasabi, B2\) 用于 CloudBitmaps

### 如何安装 @cloudbitmaps/s3？

在项目目录运行 npm install @cloudbitmaps/s3，或使用 pnpm add / yarn add / bun add。

### @cloudbitmaps/s3 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudbitmaps/s3 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cloudbitmaps/s3 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudbitmaps/s3 可以商用吗？

@cloudbitmaps/s3 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudbitmaps/s3 的下载量有多少？

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

### @cloudbitmaps/s3 还在维护吗？

最新版本 0\.27\.0 发布于 2026/11/03（6 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/09/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。