# @crvouga/mockingbird-service-vercel-blob 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-vercel-blob/

版本：1\.12\.0
npm 元数据更新时间：2026-11-13T00:12:53.543Z
中文译文更新时间：2026-11-14T16:07:46.660Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-vercel-blob
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-vercel-blob/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/vercel-blob#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.3 MB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-10-05T09:32:47.256Z
- 最新版本发布：2026-11-13T00:12:53.215Z
- 近 30 天下载量：1990（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Stateful Vercel Blob模拟器:二进制上传,公开下载,元数据,光标列表和多部分承诺.

## 安装

```sh
npm install @crvouga/mockingbird-service-vercel-blob
```

也可以使用：`pnpm add @crvouga/mockingbird-service-vercel-blob`、`yarn add @crvouga/mockingbird-service-vercel-blob`、`bun add @crvouga/mockingbird-service-vercel-blob`

## README

# @crvouga/mockingbird-service-vercel-blob (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

A 类 **阴道** 便携式 Vercel Blob 模拟器用未修改的 `@vercel/blob` **2.8.0 (中文(简体) )** SDK(英语:SDK). Blobs,多段上传,待取部件和合成下载赠款使用SQLite Collections,, 共享时钟、命名空间和时间线。 Fixtures只包含合成数据.

## 安装

```sh
bun add @crvouga/mockingbird-service-vercel-blob
```

## 使用量

该示例使用 `@vercel/blob@2.8.0`它是一种可选的消费者依赖,而不是运行时间 模拟器的依赖性 .

```ts
import { del, put } from "@vercel/blob"
import { createServer } from "@crvouga/mockingbird-service-vercel-blob/server"
import { DEFAULT_TOKEN } from "@crvouga/mockingbird-service-vercel-blob"

// Test setup: the emulator, and the two variables the Blob SDK reads.
const server = await createServer()
process.env.VERCEL_BLOB_API_URL = `${server.url}/api/blob`
process.env.BLOB_READ_WRITE_TOKEN = DEFAULT_TOKEN

// The app's own Blob calls, unchanged.
const blob = await put("fixture.txt", "fixture bytes", { access: "public", addRandomSuffix: false })
console.log(await (await fetch(blob.url)).text()) // "fixture bytes"
await del(blob.url)
await server.close()
```

SDK的支持端点覆盖是 `VERCEL_BLOB_API_URL` (或 `NEXT_PUBLIC_VERCEL_BLOB_API_URL`) (中文(简体) ). 申请 `BLOB_STORE_BASE_URL` 必须为此绘制地图 SDK被应用程序所覆盖. 对于命名空间 `suite`,使用时 `${server.url}/__admin/ns/suite/api/blob`,一个 `x-mockingbird-namespace: suite` 页眉,或注册 固定符号 `PUT /__admin/credentials`。除非 `fixtures: [{ pathname, bytes: string | number[], contentType?, cacheControlMaxAge?, storeId? }]` 提供. `tokens` 映射用于存储 ID 的合成接线符; 默认值 `DEFAULT_TOKEN` (单位:千美元)`vercel_blob_rw_fixture_fixture`地图到 `fixture`。无效或缺失的令牌返回供应商 `403 { error: { code: "forbidden", message: "Access denied" } }`。 。 。 .

SDK接受字符串,缓冲, Blob 和流. 其多段帮助者不接受原始 `Uint8Array` 键入 `PutBody`把它包入Blob或缓冲器 模拟器的 HTTP 上传处理器 保存生质 `Uint8Array` 请求正文以及字符串和任意二进制字节.

## 路线和行为

| 运行 | SDK线端点 | 行为 |
| --- | --- | --- |
| 点球 | `PUT /api/blob/?pathname=…` | Raw 字节; 公共访问、 内容类型、 缓存 TTL、 可选随机后缀、 覆盖和ETag 先决条件 |
| 读取 BlobStore | `GET /api/blob?url=…` | `head()` 元数据、大小、ETag和上传时间戳 |
| 读取 BlobStore | `GET /api/blob?prefix=…&limit=…&cursor=…&mode=…` | `list()` 使用词典路径名排序并扩展/文件夹 |
| 复制块 | `PUT /api/blob?pathname=…&fromUrl=…` | 同存储副本; 目标内容类型独立推断, 除非提供 |
| 删除块 | `POST /api/blob/delete` | `{ urls: [...] }`; 接受自己返回的 URL 或路径名; 缺失的 blobs 被忽略 |
| 多段卸载 | `POST /api/blob/mpu?pathname=…` | `x-mpu-action: create/upload/complete`, SDK 密钥/上载ID/部分编号头 |
| 下载 Blob / 下载 | `GET /__admin/blobs/{id}` 编号 : `HEAD` | 合成公共字节传输; 精确字节, ETag, Content-Length/ Type, 缓存和下载处理 |

`put()` 财务报告和审定财务报表 `copy()` 返回时 `{ pathname, url, downloadUrl, contentType, contentDisposition, etag }`。 。 。 . 上传回复确实如此 **没有** 包含大小; `head()` 并列出元数据。 复制 不覆盖返回供应商的路径名 `400 bad_request` 并保留现有的字节. 从原子角度覆盖对象并保留其URL。 有条件的写入/删除使用 `x-if-match` 返回时 `412 precondition_failed` ; 复制检查其 **来源** ETAG (英语). 删除在删除之前验证所有先决条件。 没有供应商要求识别的复制 被发明: 正常的重复路径规则适用于重复点. ETags使用SHA-256,如Vercel的 已公布的模拟器;时间戳使用被注入的时钟。 默认缓存TTL为2,592,000秒.

缓存默认值为1,000个对象,按路径名排序(所以) `file10` 首页 `file2`)并发出 `hasMore` 仅当另一个页面存在时,加光标。 模拟光标使用最后一个路径名, 如下 Vercel的模拟器;他们的编码并不是对生产不透明的光标格式的声称. 折叠 模式返回与 blob 条目分开的即时文件夹.

多段串接从不发布部分对象 。 重新加载一个部分编号替换 待定部分。 完成 验证 ETags 、 递增的独特数字、 总大小和 记录除最后部分外所有部分的最低5个小米B/等大小,然后以解剖法发布. 相同的完成重放返回已有的上传结果 . `maxBlobBytes` 默认为 20 MiB并可以配置:这是明确的本地资源约束,而不是生产配额.

公共 URL 使用配置 `publicOrigin` 或上传请求的来源。 它们包含 在保留内字节运输树内明确命名空间查询和点。 他们 通过平面工作 `fetch` 超过服务听众或进程 `emulator.fetch`。带有习惯 `adminPrefix`,字节 URL 和每个控制路径一起迁移。 时间线分支呼叫器 还必须前进 `x-mockingbird-branch` 当获取其公共 URL 时。 有条件的公众读取 支助 `If-None-Match` / 304 (中文(简体) ). 这个本地的 URL 传输是一个站入,而不是一个Vercel CDN 主机名. SDK的车 `get()` 验证生产主机名, 所以使用纯度 `fetch` 用于本地下载.

## 控制和失败

所有服务控制都住在共享的旁边 `/__admin/health`, (中文(简体) ), `/__admin/state`, (中文(简体) ), `/__admin/clock`, (中文(简体) ), `/__admin/reset`, (中文(简体) ), `/__admin/requests`故障引擎和时间线控制. `adminKey` 使用该 共享 `x-mockingbird-admin-key` 配置时守护 。 日记记录元数据并触摸 身份证 永远不要上传尸体.

| 控制权 | 目的 |
| --- | --- |
| `GET /__admin/store/blobs` | Blob 元数据, 不包括字节 |
| `POST /__admin/store/blobs` | 种子 `{ pathname, bytes: string | number[], contentType?, cacheControlMaxAge?, storeId? }` |
| `GET /__admin/store/blobs/:id/bytes` | 明确固定字节已读 |
| `GET /__admin/store/uploads` | 等待/完成上传和部分元数据,不包括字节 |
| `POST /__admin/store/origin` | 设定 `{ origin }` 用于随后的上传和固定种子 |
| `POST /__admin/store/downloads` | 创建合成 `{ blobId, expiresInMs }` 下载赠款 |
| `POST /__admin/store/downloads/:id/expire` | 立即终止赠款 |

合成赠与 URL 在共享时钟上过期并过期后返回 403; 普通公共 URL仍然公开. 这些控制不模拟生产签名协议. 预设 : `conflict`, (中文(简体) ), `rate_limited` (429 / 重试- 之后), `truncated_upload`, (中文(简体) ), `partial_multipart`, (中文(简体) ), `server_error` 财务报告和审定财务报表 `network_reset`每起火灾一次 启动 `partial_multipart` 创建后 上传,然后发送该部分失败;以前的部分仍然可供重试.

## API 密码

便携式根导出 `VercelBlobAPI`, (中文(简体) ), `createRuntime`, (中文(简体) ), `document`, (中文(简体) ), `supportedOperationIds`, (中文(简体) ), `VERCEL_BLOB_NAMESPACE`, (中文(简体) ), `VERCEL_BLOB_PRESETS`, (中文(简体) ), `DEFAULT_TOKEN`, (中文(简体) ), `DEFAULT_STORE_ID` 财务报告和审定财务报表 `DEFAULT_CACHE_MAX_AGE`,加上固定/记录/上载/赠款/运行时间选项类型. `VercelBlobAPI` 曝光情况 `fetch`, (中文(简体) ), `reset`, (中文(简体) ), `state`, (中文(简体) ), `metadata`, (中文(简体) ), `seed`, (中文(简体) ), `ensureSeeded`, (中文(简体) ), `app` 财务报告和审定财务报表 `sqlite`。 。 。 . `createRuntime` 添加共享的 MockSurface 时钟、 故障引擎、 日记、 证书 注册、状态、命名空间和时间线控制。 节点 `./server` 进口 `createServer`, (中文(简体) ), `DEFAULT_PORT` (8812个), `serveTarget` 和服务器类型; `mockingbird-vercel-blob serve` 开始一个听众.

## 甲骨文和核查

合同如下 [Vercel的 SDK 文档](https://vercel.com/docs/vercel-blob/using-blob-sdk), (中文(简体) ), 已发表 [官方SDK 2.8.0](https://www.npmjs.com/package/@vercel/blob/v/2.8.0),以及 [Vercel的官方模拟器 Blob 路线在 e4cd051](https://github.com/vercel-labs/emulate/blob/e4cd051330282a2ffc615f23d0f03c57bbd65a1e/packages/%40emulators/vercel/src/routes/blob.ts)。 。 。 . 模拟器提供有线/有线/有线/清单的证据;它明确提供 **没有** 执行多部分, 和SDK文件的多部分规则.

`bun test` 运行 SDK, 二进制接受, 所有对等的 JSON 操作行走, 一个差异 实例检查、命名空间/重置/时钟/时间线和目录预设测试。 完成的SDK测试 `put → public GET → overwrite → del` 和手动/自动多部分 对抗这个包, 不修改 SDK 或联系Vercel。 双部分接受验证失败部分 将较早的部件保存完好,只有经过验证的完成才能显示对象. `bun run parity` 凉了 只读 : `VERCEL_BLOB_API_URL` 财务报告和审定财务报表 `VERCEL_BLOB_READ_WRITE_TOKEN` 必须指定一个空测试 存储。 缺少证书或无法空入/无法进入的商店2号出入口,从没有通过现场直播的结果.

## 故意不模拟

私人商店及其授权,客户端上传签名,生产CDN/域名 路线, SDK `get()` 生产 - 主机验证绕行,范围请求,图像优化, 供应商配额、跨储存副本、真实的账单和仪表板、不透明的生产光标 编码和无文件请求ID分解没有模型化. 赠款是合成的 时钟控制。 此软件包在正常操作中永远不会联系Vercel; 只有明确 认证的、只读的等同命令就是这样做的.

## 常见问题

### @crvouga/mockingbird-service-vercel-blob 是什么？

Stateful Vercel Blob模拟器:二进制上传,公开下载,元数据,光标列表和多部分承诺\.

### 如何安装 @crvouga/mockingbird-service-vercel-blob？

在项目目录运行 npm install @crvouga/mockingbird-service-vercel-blob，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-vercel-blob，可以用 npx mockingbird-vercel-blob 直接运行。

### @crvouga/mockingbird-service-vercel-blob 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-vercel-blob 支持 ESM 还是 CommonJS？

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

### @crvouga/mockingbird-service-vercel-blob 可以商用吗？

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

### @crvouga/mockingbird-service-vercel-blob 的下载量有多少？

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

### @crvouga/mockingbird-service-vercel-blob 还在维护吗？

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