blob-s3-imgbed：把 Vercel Blob 改造成 S3 兼容图床

背景

博客评论系统 Twikoo 的图片上传依赖第三方图床，近期服务稳定性无法保证。

尝试

考虑迁移至 Cloudflare R2，因支付方式绑定受限而搁置。

结果

转向 Vercel Blob，并为其构建了一层 S3 兼容网关。

问题的由来

本站评论区由 Twikoo 驱动，其图片上传通过 imgUploader 回调实现，存储需要自行对接图床。此前一直使用 sm.ms，近期该服务可靠性明显下降：已上传的图片在数日后出现失效，且无明确公告。免费第三方图床的可持续性本就存疑，迁移势在必行。

候选方案的评估结果如下：

排除以上选项后，Vercel Blob 成为最合适的存储后端：开通即用，免费额度为 1GB 存储与每月 10GB 带宽，与本站评论区的图片量级完全匹配；且博客本身部署于 Vercel，存储与计算处于同一生态。

但它存在一个关键障碍：Vercel Blob 的 API 与 S3 不兼容——既不支持 S3 的 XML 协议，也不支持 SigV4 签名认证，官方 SDK 又只能在服务端运行。而 Twikoo 的上传行为发生在浏览器端，存储能力无法直接接入。

解决思路有二：编写一个专用的上传转发接口，或者将 Blob 完整封装为 S3 兼容服务。后者具备更普遍的复用价值，于是实现了本项目——它后来改名为 blob-s3-imgbed，并迁到了独立仓库：

Krits03/blob-s3-imgbed

把 Vercel Blob 包装成 S3 兼容 + 简单 HTTP 双接口的对象存储网关

设计与实现

项目在 Vercel Blob 之上构建网关层，对外同时提供两套接口，共享同一个 Blob Store 后端：

• S3 兼容接口：路径形如 /s3/{bucket}/{key}，支持 PUT、GET、HEAD、DELETE 四类对象操作，认证采用标准 SigV4 签名校验。任何使用 @aws-sdk/client-s3 或 AWS CLI 的调用方均可零改动接入。网关本身没有 bucket 实体，bucket 仅作为路径前缀用于逻辑分组，对象实际存储于 Blob 中 {bucket}/{key} 对应的位置。
• 简单 HTTP 接口：上传为携带 Bearer Token 的 fetch POST 请求；下载默认以 302 重定向至 Blob CDN 地址，附加 ?proxy=1 参数则切换为流式代理，隐藏源地址并支持 Range 请求。

完整请求链路如下：

技术栈：Next.js 15 App Router（Route Handler）+ @vercel/blob SDK + node:crypto。SigV4 校验是自己写的一套 HMAC 计算，没有引入 AWS SDK；签名比较使用 timingSafeEqual，避免时序侧信道。

.
├── app/
│   ├── layout.tsx                      # 根布局（metadata / html 骨架）
│   ├── page.tsx                        # 网页上传页（拖拽上传 + 复制 URL）
│   ├── s3/[...key]/route.ts            # S3 兼容接口（PUT/GET/HEAD/DELETE + SigV4）
│   └── api/
│       ├── upload/route.ts             # 简单上传接口（raw body / multipart）
│       └── download/[...key]/route.ts  # 简单下载接口（302 / 流式代理）
├── lib/
│   └── sigv4.ts                        # AWS SigV4 签名校验实现
├── .env.example                        # 环境变量模板
├── DEPLOY.md                           # 详细部署文档
├── TWIKOO_S3_CONFIG.md                 # Twikoo 管理面板 S3 插件配置指南
└── next.config.mjs

部署到 Vercel

新版把 Next.js 应用挪到了仓库根目录，Import 仓库后 Root Directory 保持默认即可，不需要再填 vercel 之类的子目录，Framework Preset 会自动识别为 Next.js。

1. 打开 Vercel Dashboard → Import 该仓库
2. 在 Settings → Environment Variables 里填入下面的变量
3. 点击 Deploy

不想点面板也可以用 CLI：

npm install -g vercel   # 如未安装
vercel                  # 首次部署（preview 环境）
vercel --prod           # 部署到生产环境

本地开发则是 npm install → 复制 .env.example 为 .env.local → npm run dev。

环境变量

密钥建议用强随机值：openssl rand -hex 32

接口参考

aws configure   # region 填 auto，AccessKey/SecretKey 用 S3_ACCESS_KEY / S3_SECRET_KEY

aws s3 cp test.jpg --endpoint-url https://<你的域名>/s3 s3://comments/test.jpg
aws s3 cp --endpoint-url https://<你的域名>/s3 s3://comments/test.jpg downloaded.jpg

# 上传
curl -X POST "https://<你的域名>/api/upload?name=test.jpg&path=test" \
  -H "Authorization: Bearer <UPLOAD_TOKEN>" \
  -H "Content-Type: image/jpeg" \
  --data-binary @test.jpg
# → { "url": "...", "key": "test/20260924/1758...-test.jpg", "contentType": "image/jpeg", "size": 10240 }

接入 Twikoo

S3 插件里最关键的几项：

twikoo.init({
  envId: '<你的 envId>',
  imgUploader: {
    async upload(file) {
      const res = await fetch(
        'https://<网关域名>/api/upload?name='
        + encodeURIComponent(file.name) + '&path=comments',
        {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer <UPLOAD_TOKEN>',
            'Content-Type': file.type,
          },
          body: file,
        }
      );
      const data = await res.json();
      return { url: data.url };
    },
  },
});

限制与费用

Hobby（免费版）额度

超限不会自动扣费，只会收到提醒邮件并暂停 Blob 功能。Edge Requests、Fast Origin Transfer 按标准 CDN 费率另计，且免费额度在项目内所有 Vercel 服务间共享。

本项目会消耗哪些额度

省额度的三条建议：

• 优先走 /api/download/{key} 的 302 重定向：浏览器直连 Blob CDN，Blob Data Transfer 平均比 Fast Data Transfer 便宜约 3 倍。
• 避免高频 HEAD 探测，每次都是 1 次 Simple Operation。
• 把 Blob 当图片存档。

其余几条硬限制：

• 上传请求体上限约 4.5 MB：上传要经 Vercel Function 中转，受 Serverless 请求体限制约束；更大文件需改用 Blob 客户端直传。
• 单 Blob 缓存上限 512 MB：超过后永不被 CDN 缓存，每次访问都会同时产生 Simple Operation 与 Fast Origin Transfer 费用。
• 单文件最大 5 TB，官方建议超过 100 MB 用 multipart 上传。
• 区域固定：Blob Store 可在 19 个区域创建，创建后不可更改，各区域价格不同。
• 控制台操作也计费：在 Vercel Dashboard 浏览文件列表、上传文件、查看详情都会计入 Operations。
• S3 接口只覆盖对象级操作：不支持 ListObjects 等 bucket 级 API —— 网关没有真实的 bucket 概念。
• 上传关闭了 addRandomSuffix，文件名依赖时间戳区分，理论上存在冲突可能。

常见问题

结语

这次改动比上次发文时更多：项目从 vercel-blob-to-s3 改名为 blob-s3-imgbed 并迁到独立仓库，Next.js 应用从子目录上移到仓库根目录，Twikoo 的接入方式也从「前端 imgUploader」换成了推荐的「管理面板 S3 插件」——密钥终于不用写进页面里了。原先的 Cloudflare Workers 版本没有跟着迁过来，新仓库里只有 Vercel 实现。

仓库里现在有两份文档：DEPLOY.md 是从零部署到 Vercel 的完整步骤，TWIKOO_S3_CONFIG.md 是 S3 插件的字段说明与排错表，比这篇文章更细。如有类似需求——不限于 Twikoo，任何需要在浏览器端使用 Vercel Blob 的场景——欢迎使用或提交 issue。

本站评论图床已切换，欢迎在评论区验证。

这应该是开学前的最后一篇了awa. 之后我会出一篇详细部署文章，敬请期待.