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

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

Beignet 的 Vercel Blob 对象存储提供者

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

此软件包适应 韦塞尔 Blob 改为 贝格纳的 StoragePort,所以在Vercel上部署的应用程序会获得耐用对象存储 没有手写适配器.

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

安装

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

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

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

bun beignet provider add storage-vercel-blob

提供者设置

// 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数字 :

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

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 不是一个授权的浏览器下载链接.

直接港口工厂

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

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 显示未整合的原始部件 覆盖 :

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是未经认证的并被长缝.