# @beignet/provider-storage-vercel-blob 中文文档

规范地址：https://npmcn.com/package/%40beignet/provider-storage-vercel-blob/

版本：0\.0\.65
npm 元数据更新时间：2026-11-07T23:22:55.362Z
中文译文更新时间：2026-11-08T09:50:07.758Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40beignet/provider-storage-vercel-blob
原文对照：https://npmcn.com/package/%40beignet/provider-storage-vercel-blob/?lang=original
项目主页：https://github.com/taylorbryant/beignet#readme
源码仓库：https://github.com/taylorbryant/beignet

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

- 包体积（解压后）：77.3 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：1 个
- peer 依赖：@vercel/blob ^2\.8\.0，@beignet/core \>=0\.0\.3 \<1\.0\.0
- 首次发布：2026-07-05T20:20:32.627Z
- 最新版本发布：2026-11-07T23:22:55.150Z
- 近 30 天下载量：1824（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 37 个）

## 中文简介

Beignet 的 Vercel Blob 对象存储提供者

## 安装

```sh
npm install @beignet/provider-storage-vercel-blob
```

也可以使用：`pnpm add @beignet/provider-storage-vercel-blob`、`yarn add @beignet/provider-storage-vercel-blob`、`bun add @beignet/provider-storage-vercel-blob`

## README

# @beignet/producer-storage-vercel-blob (中文(简体) )

> **运行时间 :** Beignet需要Node.js 22.12或更新. Bun是可选的.

> Beignet 的 Vercel Blob 对象存储提供者

> \[叹息\] Beignet是实验性的α软件. 这个 `0.0.x` 包行为早期 评估,且在框架结算时,API可能在发布之间发生变化.

此软件包适应 [韦塞尔 Blob](https://vercel.com/docs/vercel-blob) 改为 贝格纳的 `StoragePort`,所以在Vercel上部署的应用程序会获得耐用对象存储 没有手写适配器.

`createVercelBlobStorageProvider(...)` 返回稳定 `VercelBlobStorageProvider` 类型. `VercelBlobConfig` 描述其经验证的 配置; Zod schema 仍为内部.

## 安装

```bash
bun add @beignet/provider-storage-vercel-blob @vercel/blob@^2.8.0
```

`@vercel/blob` v2线内需要2.8.0或更新.

或脚手架的一切——依赖性,提供者接线,端口,env 例如, 并设置笔记——带有 CLI 预设:

```bash
bun beignet provider add storage-vercel-blob
```

## 提供者设置

```typescript
// server/providers.ts
import { createVercelBlobStorageProvider } from "@beignet/provider-storage-vercel-blob";

export const providers = [
  // ...
  createVercelBlobStorageProvider(),
] as const;
```

提供者提供 `ports.storage` (标准贝格网) `StoragePort`(中文(简体) ) 财务报告和审定财务报表 `ports.vercelBlob` (一个逃生舱口,见下文). 配置来自 `BLOB_*` env vars 和,对于OIDC认证, `VERCEL_OIDC_TOKEN`数字 :

| 新闻 var | 含义 |
| --- | --- |
| `BLOB_READ_WRITE_TOKEN` | 读写符. 以连接的 Blob 商店自动设定在 Vercel 部署上; 手动设置在其它位置 . |
| `BLOB_ACCESS` | 全库访问级别 : `private` (违约)或 `public`。 。 。 . |
| `BLOB_KEY_PREFIX` | 可选前缀适用于每个对象密钥. |
| `BLOB_STORE_ID` | 使用 Vercel OIDC 令牌认证时可选存储 ID . |
| `VERCEL_OIDC_TOKEN` | 使用 Vercel 提供的 OIDC 令牌 `BLOB_STORE_ID` 而不是一个读写符号. |

本地存储通过切换可用设备继续以零设置工作 证书,同样通过环境扩展的费率限制提供者的工作方式:

```typescript
import { createLocalStorageProvider } from "@beignet/provider-storage-local";
import { createVercelBlobStorageProvider } from "@beignet/provider-storage-vercel-blob";

const hasVercelBlobCredentials =
  Boolean(process.env.BLOB_READ_WRITE_TOKEN) ||
  Boolean(process.env.BLOB_STORE_ID && process.env.VERCEL_OIDC_TOKEN);

export const providers = [
  // Vercel Blob in deployed environments (local disk does not survive
  // serverless); the local provider keeps dev working with zero setup.
  hasVercelBlobCredentials
    ? createVercelBlobStorageProvider()
    : createLocalStorageProvider(),
] as const;
```

## 可见度

Vercel Blob 在写入时存储每个对象的访问, 但不会报告 返回从 `head(...)`,因此这个适配器保持整个商店的制服: 对象共享配置 `access` 级别,和 a `put(...)` 请求a 不同 `visibility` 以错误而不是默默拒绝 后文中误报能见度. 运行两个供应商在两个 Blob 之上 当应用程序需要两个关卡时存储.

`publicUrl(...)` 返回 blob URL 为 `public` 储存和 `null` 页:1 `private` 商店。 通过授权此软件的应用路径为私人对象服务 文件记录和呼叫 `createStorageDownloadResponse({ storage, key, fileName })` 从 `@beignet/web` 或者说 `@beignet/next`它流出一个不可取去的附件 返回时 `null` 用于丢失对象.

Vercel Blob没有任意的每个对象元数据,所以 `StorageObject.metadata` 总是报告为空。 缓存寿命图 `Cache-Control` `max-age` 给Vercel Blob的指示 `cacheControlMaxAge` 秒; 其他 指令无法幸存.

`storage.temporaryUrl(key, { expiresInSeconds, fileName? })` 验证其投入 返回时 `{ status: "unsupported" }` 不联系 Blob 或检查 存在。 使用授权的流线路径进行私人下载. 块 仅Pathname或私人 URL 不是一个授权的浏览器下载链接.

## 直接港口工厂

当您拥有供货商线路或需要第二家商店时使用直接工厂:

```typescript
import { createVercelBlobStorage } from "@beignet/provider-storage-vercel-blob";

const storage = createVercelBlobStorage({
  access: "public",
  keyPrefix: "avatars",
  storeId: process.env.AVATARS_BLOB_STORE_ID,
  token: process.env.AVATARS_BLOB_TOKEN,
});
```

奥米 `token` 允许 `@vercel/blob` 读取 `BLOB_READ_WRITE_TOKEN` 从 环境. `storeId` 明确转发给每个 SDK 操作 OIDC认证商店;SDK读取 `VERCEL_OIDC_TOKEN`,而被包围 提供者地图 `BLOB_STORE_ID` 同一选项。 这个 `client` 选项接受 假SDK表面测试.

`beignet doctor --strict` 财务报告和审定财务报表 `beignet preflight` 接受读写 符号或完整 `BLOB_STORE_ID` 加号 `VERCEL_OIDC_TOKEN` 双人.

## 请求费用

有点 `StoragePort` 承诺需要额外的 Blob API 往返:

-   `put(...)` 发布后写作 `head(...)` 因为端口返回 权威存储对象,而不是输入的回声.
-   `delete(...)` 发布删除前 `head(...)` 因为Vercel Blob的相片 `del(...)` 不报告对象是否存在.

## 逃逸舱门

`ports.vercelBlob` 显示未整合的原始部件 覆盖 :

```typescript
const { client, access, keyPrefix, storeId, objectKey, checkHealth } =
  ctx.ports.vercelBlob;

await client.list({ prefix: objectKey("exports"), limit: 100 });
const health = await checkHealth();
```

`checkHealth()` 问题的一个项目 `list(...)` 和报告 `{ ok, message?, metadata }` 准备终点.

对象密钥和 `keyPrefix` 使用共享验证和前缀帮助符 `@beignet/core/ports`,保持 Blob 行为与内存,局部,和 S3存储.

`get(...)` 返回一发响应正文。 假设一个身体方法,或调用 `await object.cancel()` 当只检查元数据时, 无法读取回复 释放资源。 偏爱 `stat(...)` 只读元数据.

## 开发工具

何时 `@beignet/devtools` 安装在此提供者之前, 存储 业务出现在仪表板的存储监视器下。 提供者的记录 `storage.put`, (中文(简体) ), `storage.get`, (中文(简体) ), `storage.stat`, (中文(简体) ), `storage.delete`, (中文(简体) ), `storage.exists`,以及 `storage.publicUrl` 带有密钥、大小和 持续时间; 失败记录为 `.failed` 事件名称和原件 错误被重写 .

## 失败行为

缺少对象 `null` (单位:千美元)`get`, (中文(简体) ), `stat`, (中文(简体) ), `publicUrl`)或(或) `false` (单位:千美元)`delete`, (中文(简体) ), `exists`(b) —— `BlobNotFoundError` 永远逃不出港口 所有其他 SDK 错误在仪器事件后未修改重排, 包括 缺少脚本错误,所以错误的配置会响亮失败而不是 假装存储是空的.

## 直接上传

此软件包覆盖服务器代理存储 `StoragePort`. Vercel (中文(简体) ) Blob 的浏览器- 直接上传使用自己的客户端- 调试协议 (单位:千美元)`@vercel/blob/client`),这不符合Beignet的平面前名PUT `UploadSignerPort`; 使用 `createS3UploadSigner` 从 `@beignet/provider-storage-s3` 当直接上传是一项要求时,或 Vercel的客户SDK直接.

## 当地测试

继续测试 `@beignet/provider-storage-local` 或者说 `createMemoryStorage()` 从 `@beignet/core/ports`; 两者执行相同 端口 。 输入假 `VercelBlobClient` 通过 `client`编号 :`createClient` 选项以测试应用程序代码来对抗此适配器而无需网络访问.

## 部署说明

连接 Blob 商店到 Vercel 工程并配置一个证书路径 : 使用情况 `BLOB_READ_WRITE_TOKEN`,或使用 Vercel OIDC 与 `VERCEL_OIDC_TOKEN` 加号 `BLOB_STORE_ID`医生、供应商审计和飞行前验证 选项而不将读写符号作为唯一有效的路径; 运行 `beignet preflight --connect` 以证明配置的商店可以到达. 偏爱 `private` 存储, 除非对象是真实的世界可读的: 公共 blob URL是未经认证的并被长缝.

## 常见问题

### @beignet/provider-storage-vercel-blob 是什么？

Beignet 的 Vercel Blob 对象存储提供者

### 如何安装 @beignet/provider-storage-vercel-blob？

在项目目录运行 npm install @beignet/provider-storage-vercel-blob，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@vercel/blob（^2\.8\.0）、@beignet/core（\>=0\.0\.3 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @beignet/provider-storage-vercel-blob 支持 TypeScript 吗？

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

### @beignet/provider-storage-vercel-blob 支持 ESM 还是 CommonJS？

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

### @beignet/provider-storage-vercel-blob 需要什么版本的 Node\.js？

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

### @beignet/provider-storage-vercel-blob 可以商用吗？

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

### @beignet/provider-storage-vercel-blob 的下载量有多少？

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

### @beignet/provider-storage-vercel-blob 还在维护吗？

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