# @cloudbitmaps/gcs 中文文档

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

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

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

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

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

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

## 中文简介

用于 CloudBitmaps 的谷歌云存储

## 安装

```sh
npm install @cloudbitmaps/gcs
```

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

## README

# @ cloudbitmaps/ gcs (英语)

**谷歌云存储 [云位图](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/gcs
```

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

`@google-cloud/storage` (单位:千美元)`^8.1.0`)是这个包的真正依赖性,所以安装是整个步骤. A 类 `client` 必须在8.1.0或以后: 驾驶员自己的测试通过8.1.0, 并且每一次尝试的旧释放都失败(8.0.1、8.0.0和7.x从7.0.0到7.22.0)。 在8.0.1上,单位测试通过,但针对仿真器的可复用上传机尾大小的集成测试却以重置连接失败. 在8.0.0和7.x的测试失败:读取驾驶员在 `readTimeoutMs` 其连接开通,其首个解答被截断了部分通道的读取没有被重试成功(该调取从未解决),而读取司机拒绝的读取并不能解除其请求. `@cloudbitmaps/core`引擎在下面,随它而来,而你却不给它起名.

## 使用

```ts
import { CloudRoaring } from '@cloudbitmaps/roaring';
import { GcsStorage } from '@cloudbitmaps/gcs';

const store = new CloudRoaring({
  storage: new GcsStorage({ bucket: 'bitmaps', prefix: 'cr' }),
});

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

它从应用程序默认身份建立自己的客户端. 任何其他密钥都会被姓名拒绝.

| 选项 | 它会做什么 |
| --- | --- |
| `bucket` (必须) | 桶头 |
| `prefix` | 此商店所写每件事的密钥前缀 |
| `client` | 你们自己 `Storage` 客户端。 通过它作为 `client`· ; `storage` 拒绝,因为 `CloudRoaring` 这个词的意思是后端 它的下载经过了它的双胞胎,SDK的重试关闭了,它的单请求有条件的写作在没有它们的情况下发送;一个客户端无法安全地从一个测试根来构建双胞胎,比如一个测试根被拒绝(见下文) |
| `projectId`, (中文(简体) ), `apiEndpoint` | 为您创建客户端, 例如为假 gcs- server 创建客户端; 拒绝 `client` |
| `simpleUploadThresholdBytes`, (中文(简体) ), `maxObjectBytes` | 一个对象的大小是简单的请求(默认为8 MiB)和最大的对象(默认为5 TiB,GCS的最大) |
| `readTimeoutMs` | a. 以毫秒计,切断一个读数; `0`,默认值,不设定超时 |
| `conditionalDelete` | 服务是否适用 `ifGenerationMatch` 在对象删除时:然后登记册删除被删除的一行,而不是留下墓碑,每一份完整的列表都读取,而存储的半部分只删除被删除的持有者。 默认关闭, 在公共端点: 是否适用真实的GCS `ifGenerationMatch` 至删除未通过针对服务的运行验证,而假gcs-server忽略它,因此CI无法显示. 设定 `true` 将行永久删除,并在GCS上关闭一个已删除的已删除的窗口,需要一代人在数字下加载,因为:当它关闭时,窗口仍然打开。 需要删除注册前缀上的许可 |

## 生产前

-   **此后端位于已验证的信封外.** 它通过与S3相同的套房,但证明 缩放和校正在S3上完成。 你是一个早期用户.
-   **运行 `await store.preflight()` 第一次载货之前.** 它会写、试图再写、读、列出和删除一个探测器 对象,并读取注册簿和桶的生命周期规则(`storage.buckets.get` 和答案 `{ ok, checks }`。它不检查删除或版本后的读取,除其他外: [完整列表](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#what-preflight-does-not-check)第一次是八次请求.
-   **授予水桶的物体权限.** 库创建、读取、列出和删除对象: `roles/storage.objectAdmin` 盖取四相.
-   **即刻写保证通过GCS先决条件** (单位:千美元)`ifGenerationMatch`)),所以不需要其他的帮助.
-   **永不添加过期当前对象或 `registry/` 前缀.**
-   **检查桶的生命周期规则 `await backend.checkLifecycle()`。 。 。 .** 它读出一个桶的元数据 请求 `readTimeoutMs`和答案 `problem` (单位:千美元) `Delete` 适用于活对象并能匹配前缀的规则, `ok`,或 `unchecked`它需要 `storage.buckets.get`负载从来不用, `store.preflight()`生命周期步骤有,而且 `roles/storage.objectAdmin` 已经 不包括:没有答案是: `unchecked`,命名权限 (单位:千美元)[从代码中检查生命周期规则](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md#check-the-lifecycle-rules-from-code)) (中文(简体) ).
-   **SDK不重试下载;驱动程序有.** 单位 `@google-cloud/storage` 8.x(在8.1.0上检查)和7.x(在8.1.0上检查) 7.22.0,此驱动程序范围之外的发布),在任何状态重试后下载SDK重试(408,429,500,502,503或504)可以崩溃进程 与 `ERR_STREAM_UNABLE_TO_PIPE`尽管重审请求成功, 客户 `GcsStorage` 因此,构建将每次下载发送一次,驱动程序自己再次运行一次下载,最多还有三次 在连接断层(重排、重置、超时、DNS故障、身体被切断)或408,429后, 500,502,503或504,再无其他(不是缺失的证书文件或TLS故障). 这对每一个 包括一家商店 `retry: false`。客户端的列表、删除、可更新的上传和 读取解决写入的元数据保留其重试设置( SDK 在其中不设先决条件的情况下发送删除) ; 单请求有条件的写入(一个注册行,一个小的一代),在没有它们的情况下发送. **一个客户你 通过为 `client` 对这些请求保留自己的回覆**:它的下载通过它的双胞胎,由它自己建造 具有相同证书对象、终点、项目、用户代理、超时、校验和生成器和截取器的类 和SDK的回击关闭。 A 类 `Storage` 客户端总是通过它的双胞胎使用,双胞胎必须使用以下设置: 决定下载地点和方式:相同的证书对象、 URL 和端点, 以及重试自己的设置, 然后,他们将被关闭在他们所有的等级之上。 后端在建成后拒绝一个双胞胎的客户端 (一个从自己的选项建立起来的子类),一个其类凌驾于它之上的子类 `bucket` (作为测试的双倍 建立在 `Storage` 和谁的 `bucket` 在实例中被替换(如测试根节)。 稳住 `Storage.prototype` (或 `Bucket.prototype`, (中文(简体) ), `File.prototype`),它到达了双胞胎;客户身上的根不是. A 类 测试双倍,不是 `Storage` 客户端被使用时的状态 `retryOptions: { autoRetry: false }`,以及 在SDK的模块被嘲笑的情况下,通过模拟器 `client`。后端后端对客户端设置什么 除了拦截器外,其他设备不带给双胞胎.
-   **一个客户 `timeout` 不绑定下载于 `@google-cloud/storage` 8.x 电话**,所以读取其服务器站等待 对于它。 对一个从未回答的本地服务器进行测量:12 s之后仍未答复 `timeout: 2000`。 。 。 . **`readTimeoutMs` 是的,它关闭,除非你设置它.** 它将每个读作整体:一代人尾巴(与 读取的元数据会返回到空对象、其中的某个范围或一个注册行。 一个期限涵盖每个 尝试驾驶员和他们之间的后退,从呼叫到驾驶员(证书获取器和任何 等待插座计数)到身体末端. 计算进程花费的时间也繁忙: 节点运行一个适当的计时器 在它读出插座之前, 同步的长度比超时的长度长, 飞行中的读取失败, 即使他们 答复已经到来。 当它通过, 读出 `TransientError` 命名读取和超时,没有 进一步尝试开始; 商店的读取重试再次运行它, 因此 `readTimeoutMs: 2_000` 读取一个摊位 每一次尝试在大约8.35 s(4×2 s+可达0.35 s后退;测量:8.1至8.2 s)后都失败. 上传, 删除和列表没有定时.
-   **在它的服务器回答之前读出的时间会打开它的连接 .** SDK 无法取消请求 其响应尚未开始,所以该请求在服务器回答或关闭之前一直保持连接,直到 然后不让节点进程退出:每个司机读出一个,通过商店的再试,每个调用最多四个,所以 n的断电量每秒增加大约4N的连接量。 每个版本的司机范围都承认 (8.1.0和后一) 答复开始关闭之后的读取断接;8.0.0和7.x(7.2.2.),两者均关闭 在范围外,它保持开放。 一个404的 错误体到达之后 截止日期报告为 `TransientError`没有 `NotFoundError`。 。 。 .
-   **在Node的全球代理上下载出去,所以一个驱动程序切断或拒绝任何其它的重新发送.** 当a 下载部分失败 SDK摧毁了它出去的HTTP代理, 并且它自己的代理是 保持- 静电池 整个流程共享,所以飞行中的所有其它请求都会与它重置,包括上传. SDK从来没有 摧毁全球特工。 用8.1.0测量,没有超时: 身体被截断 半程重置一个64字节上传和一个 登记员在SDK的代理的第二个后端上写作,并在全球代理上写作全部完成. 费用: 全局代理关闭一个闲置的连接 5 秒( SDK 的自有池没有), 因此在较长暂停后读取 打开一个新的连接, 与其 TCP 和 TLS 握手, 下载时与任何其他人共享此代理 `http` 或者说 `https` 请求。 抚养 `https.globalAgent.options.timeout` 保持闲置的连接更长.
-   **写作的瞬间失败 `TransientError`,而写作可能已经着陆,也可能没有着陆.** 重开电话, 或检查 `store.generations(ref)`驱动程序 [发送每个注册文件 一次](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个 时间。 一代人的目标 `simpleUploadThresholdBytes` 重复发送,最多再发送三次, 只有在 `429` 或者说 `503`;每个对象在其元数据中都带有随机的id,所以第一个登陆的发件是从另一个发送的 作家对象. 排行写字的负载都会被解答 `TransientError` 并保持它的对象。 等待着 在对象的再发送使用实时计时器之前:商店的注入时钟没有到达它们,以及 `GcsStorage` 采取不 时钟,所以一个测试 节流器一个物体写出三次 最多等待3.5秒左右( 出版者等待 a) 新鲜行写确实使用商店的时钟).

这个 [生产清单](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/production.md) 覆盖每个项目,以及每个后端共享的项目:数据备份和注册,以及您负载的时间表.

-   **驾驶员在丢弃前会校正其识别出的错误的证书 .** SDK保持反应 获取错误( e)`response`和它通过它发出的要求,及其无记名的迹象 `Authorization` 信头和 HTTP 代理机与其他呼叫共享; 重复上传或符号请求错误保留 请求的 `config`。在下载时,只要一个身体没有列出任何错误,SDK就会使反应机构产生错误 消息,所以一个代理的页面或引用请求的JSON正文将符号放入消息中. 在错误中 驱动程序投掷,证书名称下的值被替换 `[redacted]` (单位:千美元)`authorization`, (中文(简体) ), `x-goog-encryption-key`, (中文(简体) ), `x-goog-api-key`, (中文(简体) ), `X-Goog-Signature`, (中文(简体) ), `X-Goog-Credential`, (中文(简体) ), `access_token`, (中文(简体) ), `refresh_token`, (中文(简体) ), `client_secret`, (中文(简体) ), `private_key` 等;服务账户的 `client_email` 财务报告和审定财务报表 `private_key_id` 保存),因此 是在页眉列表中或地图下的一个之后的值,是记录中一个旁边的值(a) `{ name, value }` 双对, a `{ th, td }` 行; 数字、布尔和 `message`, (中文(简体) ), `reason` 财务报告和审定财务报表 `location` google 错误项目为 (a) 其文本中的任何一处,都有一个证书头行 `Authorization` 值, 加密密钥, API密钥, oAuth 令牌或客户端秘密, 或签名的 URL 签名或证书后的名称; 饼干头的值 名称后; 计划后无记名标志; 谷歌访问标志(`ya29.`)或单用JWT 网页 `Signature=`; PEM 私人密钥的正文; 为证书命名的元素的正文, 如 `<CanonicalRequest>` 服务引用回; 单元格的文本取自命名证书的单元格后( a) `<th>`编号 :`<td>` 单行, a `<dt>`编号 :`<dd>` ,在标题或标题之后。 另一种形式的证书不是 已识别( 按列、 用户和密码写入 URL、 冒号写为 HTML 的页眉表) 实体,例如 `&colon;` 这些步骤无法完成的文字将被替换 整个。 SDK错误,它载运或显示证书,以及它所达到的每一个错误(它) `cause` 链条, a 一个 `AggregateError`是因为 `errors`),被抛出为复制:一个原型,名称,消息,堆栈, `code`, (中文(简体) ), `status` 财务报告和审定财务报表 `errors`,与 `response` 减为状态和状态文本,所以分类不变, 无 `config`、请求、其代理人或套接字、任何函数或存取器财产,或比 10级。 直播错误从未改变, 仅保存纯数据且未显示证书的错误会被丢弃 如来相.

## 文档

-   [开始](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/gcs 是什么？

用于 CloudBitmaps 的谷歌云存储

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

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

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

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

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

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

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

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

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

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

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

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

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

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