用途
Vercel Blob 用于在 Next.js 应用中集成文件上传与 CDN 分发的资源存储能力。本技能基于 @vercel/blob@2.0.0（技能版本 2.1.0，最后更新 2026-01-21），提供从环境配置、上传、管理到问题预防的完整实践指引。
主要能力
- 服务端上传：在 Server Action 中使用 put() 上传文件并返回可访问的 blob URL。
- 客户端安全上传：通过 handleUpload() 生成带约束的预签名令牌，避免将 BLOB_READ_WRITE_TOKEN 暴露到客户端。
- 大文件分片传输：支持 multipart 上传，突破单次上传体积限制。
- 文件管理：使用 list() 进行基于游标的分页列举，使用 del() 删除文件。
- 访问控制：通过 access: 'public' 或 'private' 控制文件是否经 CDN 缓存公开访问。
使用方式
快速开始：在 Vercel Dashboard 的 Storage → Blob 创建 Blob store，运行 vercel env pull .env.local 生成 BLOB_READ_WRITE_TOKEN，然后 npm install @vercel/blob。
服务端上传示例：
'use server';
import { put } from '@vercel/blob';
export async function uploadFile(formData: FormData) {
const file = formData.get('file') as File;
const blob = await put(file.name, file, { access: 'public' });
return blob.url;
}
客户端上传需由服务端生成令牌，客户端组件再调用 upload() 并传入 handleUploadUrl。文件列举与删除使用 list() 与 del()，超过 500MB 的文件需使用 createMultipartUpload / uploadPart / completeMultipartUpload。
适用场景
- 头像上传与替换（先删除旧文件再写入新文件并更新数据库）。
- 受保护文档存储（access: 'private'）。
- 需要 CDN 加速的公开图片、视频等静态资源分发。
- 需要绕过服务端 4.5MB 请求体限制的大文件上传。
限制与关键规则
必须遵守：客户端上传一律使用 handleUpload()，绝不暴露 BLOB_READ_WRITE_TOKEN；上传前校验文件类型与大小；用 pathname 组织目录（如 avatars/、uploads/）；文件名加入时间戳或 UUID 避免冲突。禁止：向客户端暴露令牌；超过 500MB 不使用分片上传；跳过文件校验。
本技能整理了 16 个已知问题及预防措施，主要包括：环境变量缺失、客户端令牌暴露、文件超过 500MB 限制、Content-Type 设置错误导致浏览器下载而非展示、公开文件误用 private 导致未被缓存、list 分页未处理只返回前 1000 个文件、删除静默失败、服务端上传超时与 4.5MB 服务端请求体硬限制、文件名冲突覆盖、缺少 onUploadCompleted 回调、大文件令牌 30 秒过期、v2.0.0 在非 Vercel 托管下 onUploadCompleted 需显式提供 callbackUrl、Firefox 不支持 ReadableStream 作为 fetch body、onBeforeGenerateToken 中 pathname 不可修改、手动分片每片最小 5MB 与服务端限制冲突、pathname 缺少扩展名导致 Access denied。
其他事实（如具体收费、价格、平台支持范围）暂未提供。