name: vercel-kv description: Vercel KV（通过Upstash实现的Redis兼容键值存储）。用于Next.js缓存、会话、速率限制、TTL数据存储，或解决KV_REST_API_URL错误、速率限制问题、JSON序列化错误。提供强一致性而非最终一致性。

关键词：vercel kv、@vercel/kv、vercel redis、upstash vercel、kv vercel、redis vercel edge、key-value vercel、vercel cache、vercel sessions、vercel rate limit、redis upstash、kv storage、edge kv、serverless redis、vercel ttl、vercel expire、kv typescript、next.js kv、server actions kv、edge runtime kv license: MIT

Vercel KV（Redis兼容存储）

状态：生产就绪 最后更新：2025-12-14 依赖项：无 最新版本：@vercel/kv@3.0.0

快速开始（3分钟）

1. 创建与配置

# 在Vercel仪表板中创建KV数据库：存储 → 创建数据库 → 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;
}

边缘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`
使用管道进行批量操作	单次往返减少延迟
仅序列化JSON兼容数据	不使用函数、循环引用
监控命令使用	保持在免费层内（30K/月）

绝不执行

规则	原因
存储未加密的敏感数据	KV默认未加密存储
忘记设置TTL	无TTL的键永久保留
使用通用键名	`data`、`cache` 会冲突
存储大值（>1MB）	改用Vercel Blob
用作主数据库	KV用于缓存，非持久存储
提交 `.env.local`	包含KV令牌

核心操作

带TTL的设置/获取：

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

// 设置带TTL（1小时后过期）
await kv.setex('session:abc', 3600, { userId: 123 });

// 获取值
const session = await kv.get('session:abc');

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

原子操作：

const views = await kv.incr('views:post:123');
const wasSet = await kv.setnx('lock:process', 'running'); // 如果不存在则设置

多键操作：

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 未定义`	运行 `vercel env pull .env.local`
2	`无法序列化 BigInt`	转换为字符串，使用普通对象
3	意外数据返回	使用命名空间键：`user:123:profile`
4	内存无限增长	使用带TTL的 `setex()`
5	速率限制超出	批量操作，升级计划
6	值过大	使用Vercel Blob处理 >100KB
7	TypeScript类型错误	使用 `kv.get<Type>()` 配合Zod验证
8	管道静默失败	检查来自 `exec()` 的结果数组
9	扫描超时错误	限制计数，使用游标迭代
10	会话过早过期	使用 `expire()` 实现滑动窗口

参见：references/known-issues.md 获取带代码示例的完整解决方案。

常见模式总结

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

参见：references/common-patterns.md 获取完整实现。

配置

.env.local

# 由以下命令创建：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 未定义`	运行 `vercel env pull .env.local`
速率限制超出	使用 `mget`/管道，升级计划
值未过期	使用 `setex()` 而非 `set()`
JSON序列化错误	使用普通对象，将BigInt转换为字符串