vercel-blob

Vercel Blob（对象存储）

状态：已可用于生产环境 最后更新：2025-12-14 依赖项：无 最新版本：@vercel/[email protected]

---

快速开始（3 分钟）

1. 创建并配置

# In Vercel dashboard: Storage → Create Database → Blob
vercel env pull .env.local

创建：BLOB_READ_WRITE_TOKEN

2. 安装

bun add @vercel/blob

3. 上传文件（服务端操作）

'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',
    contentType: file.type
  });

  return blob.url;
}

4. 基本操作

import { put, del, list } from '@vercel/blob';

// Upload
const blob = await put('path/file.jpg', file, { access: 'public' });

// Delete
await del(blob.url);

// List with pagination
const { blobs, cursor } = await list({ prefix: 'uploads/', limit: 100 });

---

关键规则

始终执行

规则	原因
客户端上传时使用客户端上传令牌	切勿向客户端暴露 BLOB_READ_WRITE_TOKEN
显式设置 contentType	确保浏览器正确处理 PDF、视频等文件
使用 access: 'public' 以启用 CDN 缓存	私有文件不会经过 CDN
上传前验证文件类型和大小	防止上传无效文件
按路径名组织文件	avatars/、uploads/、documents/
替换文件时删除旧文件	控制存储成本

切勿执行

规则	原因
向客户端暴露 BLOB_READ_WRITE_TOKEN	安全漏洞
未使用分片上传就上传大于 500MB 的文件	使用 createMultipartUpload API
使用通用文件名	使用 ${Date.now()}-${name} 或 addRandomSuffix: true
跳过文件验证	始终验证类型和大小
未加密就存储敏感数据	上传前先加密
忘记处理分页	list() 最多返回 1000 个文件

---

已知问题预防

此技能可预防 10 个已记录问题：

#	错误	快速修复
1	BLOB_READ_WRITE_TOKEN not defined	运行 vercel env pull .env.local
2	客户端令牌泄露	使用 handleUpload() 进行客户端上传
3	文件超出大小限制（500MB）	使用分片上传 API
4	content-type 错误	设置 contentType: file.type
5	未启用 CDN 缓存	使用 access: 'public'
6	列表中缺少文件	使用游标分页
7	删除操作静默失败	使用 put() 返回的确切 URL
8	上传超时	大文件使用客户端上传
9	文件名冲突	添加时间戳或使用 addRandomSuffix: true
10	状态未更新	使用 onUploadCompleted 回调

参见：references/known-issues.md，其中包含完整解决方案和代码示例。

---

常见模式摘要

模式	用例	关键 API
头像上传	用户个人资料图片	put、del
受保护的上传	私有文档	使用 access: 'private' 的 put
图片库	列出并分页	使用游标的 list
客户端上传	大文件、进度	upload、handleUpload
分片上传	大于 500MB 的文件	createMultipartUpload、uploadPart
批量操作	多个文件	Promise.all、del([...])
图片处理	上传前优化	sharp + put

参见：references/common-patterns.md，其中包含完整实现。

---

客户端上传（必要模式）

服务端操作（令牌生成）：

'use server';

import { handleUpload, type HandleUploadBody } from '@vercel/blob/client';

export async function generateUploadToken(body: HandleUploadBody) {
  return await handleUpload({
    body,
    request: new Request('https://dummy'),
    onBeforeGenerateToken: async (pathname) => ({
      allowedContentTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maximumSizeInBytes: 5 * 1024 * 1024
    }),
    onUploadCompleted: async ({ blob }) => {
      // Save to database
      await db.insert(uploads).values({ url: blob.url, pathname: blob.pathname });
    }
  });
}

客户端组件：

'use client';

import { upload } from '@vercel/blob/client';

const blob = await upload(file.name, file, {
  access: 'public',
  handleUploadUrl: '/api/upload'
});

---

配置

.env.local

# Created by: vercel env pull .env.local
BLOB_READ_WRITE_TOKEN="vercel_blob_rw_xxxxx"

.gitignore

.env.local
.env*.local

---

何时加载参考资料

参考资料	加载时机……
references/known-issues.md	调试上传错误、令牌问题或 CDN 缓存问题时
references/common-patterns.md	实现头像上传、图片库、客户端上传或分片上传时

---

依赖项

{
  "dependencies": {
    "@vercel/blob": "^2.0.0"
  }
}

免费套餐限制：每月 100GB 带宽，文件大小上限为 500MB

---

官方文档

• Vercel Blob：https://vercel.com/docs/storage/vercel-blob
• 客户端上传：https://vercel.com/docs/storage/vercel-blob/client-upload
• SDK 参考：https://vercel.com/docs/storage/vercel-blob/using-blob-sdk
• GitHub：https://github.com/vercel/storage

---

故障排除

问题	解决方案
BLOB_READ_WRITE_TOKEN not defined	运行 vercel env pull .env.local
文件大小超出限制（>500MB）	使用分片上传 API
客户端上传失败	在服务端使用 handleUpload()
文件未删除	使用 put() 响应中的确切 URL

---

节省 Token：约 60%（将模式提取到参考资料中） 错误预防：100%（记录了全部 10 个问题） 已可用于生产！