vercel-kv

Vercel KV（兼容 Redis 的存储）

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

---

快速开始（3 分钟）

1. 创建并配置

# Create KV database in Vercel dashboard: Storage → Create Database → KV
vercel env pull .env.local

创建环境变量：

• KV_REST_API_URL - KV 数据库 URL
• KV_REST_API_TOKEN - 身份验证令牌

2. 安装

bun add @vercel/kv

3. 在应用中使用

Next.js 服务端操作：

'use server';

import { kv } from '@vercel/kv';

export async function incrementViews(slug: string) {
  const views = await kv.incr(`views:${slug}`);
  return views;
}

Edge API 路由：

import { kv } from '@vercel/kv';

export const runtime = 'edge';

export async function GET(request: Request) {
  const value = await kv.get('mykey');
  return Response.json({ value });
}

---

关键规则

始终执行

规则	原因
为临时数据设置 TTL	setex('key', 3600, value) - 避免内存泄漏
使用带命名空间的键	使用 user:123:profile，而非 123 - 防止冲突
处理 null 返回值	不存在的键会返回 null
使用 pipeline 批量操作	单次往返可降低延迟
仅序列化兼容 JSON 的数据	不支持函数和循环引用
监控命令用量	确保不超出免费层级（每月 30K）

绝不执行

规则	原因
不加密就存储敏感数据	默认情况下，KV 的静态数据未经加密
忘记设置 TTL	未设置 TTL 的键会永久保留
使用通用键名	data、cache 会发生冲突
存储较大的值（>1MB）	请改用 Vercel Blob
将其用作主数据库	KV 用于缓存，而非持久化存储
提交 .env.local	其中包含 KV 令牌

---

核心操作

设置/获取并设置 TTL：

import { kv } from '@vercel/kv';

// Set with TTL (expires in 1 hour)
await kv.setex('session:abc', 3600, { userId: 123 });

// Get value
const session = await kv.get('session:abc');

// Delete
await kv.del('session:abc');

原子操作：

const views = await kv.incr('views:post:123');
const wasSet = await kv.setnx('lock:process', 'running'); // Set if not exists

多个键：

const values = await kv.mget('user:1', 'user:2', 'user:3');
await kv.mset({ 'user:1': data1, 'user:2': data2 });

---

预防已知问题

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

#	错误	快速修复
1	KV_REST_API_URL not defined	运行 vercel env pull .env.local
2	Cannot serialize BigInt	转换为字符串，并使用普通对象
3	返回了意外数据	使用带命名空间的键：user:123:profile
4	内存持续增长	使用带 TTL 的 setex()
5	超出速率限制	批量操作，或升级套餐
6	值过大	对于 >100KB 的值，请使用 Vercel Blob
7	TypeScript 类型错误	使用 kv.get<Type>() 并通过 Zod 验证
8	Pipeline 静默失败	检查 exec() 返回的结果数组
9	Scan 超时错误	限制数量，并使用游标迭代
10	会话过早过期	使用 expire() 实现滑动窗口

请参阅：references/known-issues.md，查看包含代码示例的完整解决方案。

---

常见模式摘要

模式	使用场景	关键 API
旁路缓存	读取缓存	get → fetch → setex
直写缓存	写入一致性	写入时使用 setex，删除时使用 del
速率限制	API 保护	incr + expire
会话管理	用户会话	setex、get、expire、del
分布式锁	并发控制	setnx + expire + del
排行榜	排名	zadd、zrange、zrevrank
Pipeline	批量操作	pipeline().exec()

请参阅：references/common-patterns.md，查看完整实现。

---

配置

.env.local

# Created by: vercel env pull .env.local
KV_REST_API_URL="https://your-database.kv.vercel-storage.com"
KV_REST_API_TOKEN="your-token-here"

.gitignore

.env.local
.env*.local

---

何时加载参考资料

参考资料	加载时机
references/known-issues.md	调试 KV 错误、类型问题或性能问题时
references/common-patterns.md	实现缓存、会话、速率限制、排行榜或锁时

---

依赖项

{
  "dependencies": {
    "@vercel/kv": "^3.0.0"
  }
}

免费层级限制：每月 30,000 条命令，256MB 存储空间

---

官方文档

• Vercel KV：https://vercel.com/docs/storage/vercel-kv
• SDK 参考：https://vercel.com/docs/storage/vercel-kv/kv-reference
• GitHub：https://github.com/vercel/storage
• Redis 命令：https://redis.io/commands

---

故障排除

问题	解决方案
KV_REST_API_URL not defined	运行 vercel env pull .env.local
超出速率限制	使用 mget/pipeline，升级套餐
值未过期	使用 setex()，而不是 set()
JSON 序列化错误	使用普通对象，将 BigInt 转换为字符串

---

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