# @edgeone/pages-blob 中文文档

规范地址：https://npmcn.com/package/%40edgeone/pages-blob/

版本：0\.0\.19
npm 元数据更新时间：2026-11-07T06:00:21.446Z
中文译文更新时间：2026-11-13T06:43:17.840Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40edgeone/pages-blob
原文对照：https://npmcn.com/package/%40edgeone/pages-blob/?lang=original

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

- 包体积（解压后）：37.6 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-05-08T06:56:39.709Z
- 最新版本发布：2026-11-07T06:00:21.233Z
- 近 30 天下载量：67362（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Blob 为边缘一页函数存储 SDK

## 安装

```sh
npm install @edgeone/pages-blob
```

也可以使用：`pnpm add @edgeone/pages-blob`、`yarn add @edgeone/pages-blob`、`bun add @edgeone/pages-blob`

## README

# @ edgeone/ pages- blob (英语)

Blob 为 Edge One Pages 函数存储 SDK,提供持续的密钥值存储,跨部署.

## 安装

```bash
npm install @edgeone/pages-blob
```

## 使用量

### Pages 函数( 自动认证)

```js
import { getStore } from "@edgeone/pages-blob";

const store = getStore("my-store");

// Write
await store.set("key", "value");
await store.setJSON("config", { theme: "dark" });

// Read
const text = await store.get("key");
const json = await store.get("config", { type: "json" });

// Delete
await store.delete("key");

// List
const { blobs } = await store.list({ prefix: "users/" });
```

### 外部访问( API Token 模式)

从外部调用 Page 函数时, 您必须提供 **两者** `token` 财务报告和审定财务报表 `projectId`。 。 。 .

获取您的 API 打开这里: [https://pages.edgeone.ai/document/api-token 页面存档备份,存于互联网档案馆](https://pages.edgeone.ai/document/api-token)

```js
const store = getStore({
  name: "my-store",
  projectId: "makers-urtsvuwmfvli", // required
  token: "c+KH5...", // required
});
```

选择 `projectId` 掷出 `MissingProjectIdError`。 。 。 .

### 一致性强(读后写)

默认读取使用最终一致性(CDN-cached,低延迟). 改为: 保证后读一致,使用 `"strong"`数字 :

```js
// Store-level default — all reads use strong consistency
const store = getStore({ name: "my-store", consistency: "strong" });

// Per-call override
await store.get("key", { consistency: "strong" });
await store.list({ consistency: "strong" });
```

`"eventual"` 缓缓的; `"strong"` 保证 以绕过缓存层为代价的最新值 .

### 列出所有仓库

```js
import { listStores } from "@edgeone/pages-blob";

// Inside Pages Functions
const { stores } = await listStores();

// External access (token mode) - both fields required
const { stores } = await listStores({
  projectId: "pages-urtsvuwmfvli",
  token: "c+KH5...",
});
```

### 从浏览器直接上传( 指定 URL)

对于大型文件上传,将浏览器交给一个预先签名的PUT URL,并让它 字节直接流到 Pages Blob —— 您的函数只看到一个很小的 URL 请求,而不是文件本身.

```js
// Function side — generate a one-shot upload URL
import { getStore } from "@edgeone/pages-blob";

export async function onRequest({ request }) {
  const { name } = await request.json();
  const store = getStore("uploads");
  const { url, key, expiresAt } = await store.createUploadUrl(`files/${name}`, {
    expireSeconds: 3600,            // optional, default 3600
    contentType: "application/octet-stream", // optional, binds Content-Type
  });
  return Response.json({ url, key, expiresAt });
}
```

```js
// Browser side — plain fetch, no SDK needed
const { url, key } = await fetch("/api/get-upload-url", {
  method: "POST",
  body: JSON.stringify({ name: file.name }),
}).then((r) => r.json());

await fetch(url, {
  method: "PUT",
  body: file,                       // File / Blob / ArrayBuffer
  headers: { "Content-Type": "application/octet-stream" }, // must match if `contentType` was set
});
// Bytes go straight from the browser to Pages Blob, never through your Function.
```

签名将 URL 绑定为: PUT 方法, 准确的密钥, 时间窗口 , 和(可选)内容类型。 其他方法,其他密钥,过期的 URL, 和不匹配的内容- Type 全部返回 403 .

## API 密码

### `getStore(name | options)`

获取 Store 实例 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `string` | 存储名称 |
| `options.name` | `string` | 存储名称 |
| `options.projectId` | `string` | 项目标识( E)**所需经费** (供外部使用) |
| `options.token` | `string` | 访问令牌( A)**所需经费** (供外部使用) |
| `options.consistency` | `"eventual" | "strong"` | 默认读取一致性( 默认) `"eventual"`(中文(简体) ) |

### `store.set(key, value, options?)`

写个Blob. `value` 支持 `string | ArrayBuffer | Blob | ReadableStream`。 。 。 .

### `store.setJSON(key, value, options?)`

写入 JSON( 自动序列化 ) 。 接受同样的 `options` 作为 `store.set`。 。 。 .

### `store.get(key, options?)`

读一个Blob。 回返 `null` 如果它不存在的话.

-   `options.type`数字 : `"text"` (默认) `"json"` | `"arrayBuffer"` | `"blob"` | `"stream"`
-   `options.consistency`数字 : `"eventual"` | `"strong"` (覆盖存储级别默认值)

### `store.getWithHeaders(key, options?)`

读取一个blob 连同所有响应标题。 回返 `null` 如果密钥不存在.

回返情况: `{ body: string, headers: Record<string, string> }`

-   `options.consistency`数字 : `"eventual"` | `"strong"`

### `store.delete(key)`

删除 Blob .

### `store.list(options?)`

名单 Blobs. 默认情况下自动汇总所有页面.

-   `options.prefix`: 前缀过滤器
-   `options.directories`: 按目录分组
-   `options.limit`: 要返回的最大blob数( 默认: 所有)
-   `options.paginate`: 设置为 `false` 手动页标
-   `options.cursor`: 从上一个页形光标恢复
-   `options.consistency`数字 : `"eventual"` | `"strong"`

回返情况: `{ blobs: Array<{ key, etag }>, directories: string[] }`

### `store.createUploadUrl(key, options?)`

构建一个预先签名的 PUT URL,以便浏览器/客户端可以直接向上传文件 Pages Blob, 不需要字节流过您的功能 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `key` | `string` | 块键 |
| `options.expireSeconds` | `number` | 有效窗口( 秒) (默认) `3600`(中文(简体) ) |
| `options.contentType` | `string` | 绑定一个内容- Type —— 客户端 MUST 在其 PUT 上响应此标题 |

回返情况: `{ url: string, key: string, expiresAt: number }` 地点 `expiresAt` 是一个以秒计的Unix时间戳.

URL与PUT+这个精确的密钥+签名时间窗口(和 可选内容-Type). 任何其它用途返回 403.

### `listStores(options?)`

列出项目下的所有 Store .

-   `options.projectId`: 项目ID (**所需经费** (供外部使用)
-   `options.token`: 访问符 (**所需经费** (供外部使用)
-   `options.consistency`数字 : `"eventual"` | `"strong"`

回返情况: `{ stores: Array<{ name: string }> }`

## 超过配额

当超过自由计划时, `store.set()`, (中文(简体) ), `store.setJSON()` 财务报告和审定财务报表 `store.createUploadUrl()` 掷出 `QuotaExceededError` (单位:千美元)`code: "QUOTA_EXCEEDED"`(中文(简体) ) 在发送任何字节之前.

| `err.reason` | 还行 |
| --- | --- |
| `"storage"` | 读取,删除 |
| `"complex-operations"` | 读取,删除 |
| `"egress"` | 删除 |

`err.overMetrics` 列出目前每个超过限度的度量,例如:. `["pages-blob-storage"]`。 。 。 .

```js
import { QuotaExceededError } from "@edgeone/pages-blob";

try {
  await store.set("key", value);
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // err.reason === "storage" → delete objects or upgrade the plan
  }
}
```

用法定期检查,所以写作可以持续几分钟 过了极限后 继续失败几分钟 背着它.

URL 来自 `createUploadUrl()` 在超过配额之前发放的 在浏览器的PUT上以403,550或重置连接失败; SDK 无法 看看这个反应.

## 常见问题

### @edgeone/pages-blob 是什么？

Blob 为边缘一页函数存储 SDK

### 如何安装 @edgeone/pages-blob？

在项目目录运行 npm install @edgeone/pages-blob，或使用 pnpm add / yarn add / bun add。

### @edgeone/pages-blob 支持 TypeScript 吗？

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

### @edgeone/pages-blob 支持 ESM 还是 CommonJS？

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

### @edgeone/pages-blob 需要什么版本的 Node\.js？

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

### @edgeone/pages-blob 可以商用吗？

@edgeone/pages-blob 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @edgeone/pages-blob 的下载量有多少？

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

### @edgeone/pages-blob 还在维护吗？

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