vercel-kv

用途

Vercel KV 是一个与 Redis 兼容的键值存储服务，由 Upstash 提供支持，旨在为 Next.js 应用提供缓存、会话管理和速率限制等功能。它通过 @vercel/kv 包（版本 3.0.0）集成，提供强一致性和 TTL（生存时间）支持。

主要能力

• 缓存：支持缓存旁路模式，可存储和检索数据，并设置过期时间。
• 会话管理：可存储会话数据，并设置较长的 TTL（如 7 天）。
• 速率限制：通过原子递增和过期实现简单的速率限制。
• 管道操作：支持批量执行多个命令，减少网络往返。
• 数据结构：支持字符串、哈希、有序集合等 Redis 数据结构。

使用方式

1. 创建 KV：在 Vercel 仪表板中，进入 Storage → KV 创建。
2. 获取环境变量：运行 vercel env pull .env.local 以获取 KV_REST_API_URL 和 KV_REST_API_TOKEN。
3. 安装包：运行 npm install @vercel/kv。
4. 基本用法：

   import { kv } from '@vercel/kv';
   // 设置带 TTL 的值（1 小时后过期）
   await kv.setex('session:abc', 3600, { userId: 123 });
   // 获取值
   const session = await kv.get('session:abc');
   // 原子递增
   const views = await kv.incr('views:post:123');
   

5. 常见模式：
   • 缓存：先检查缓存，未命中则查询数据库并设置缓存。
   • 速率限制：使用 incr 和 expire 实现固定窗口限流。
   • 会话管理：生成会话 ID 并存储用户数据。
   • 管道：使用 kv.pipeline() 批量执行命令。

适用场景

• Next.js 应用中的缓存层，减少数据库负载。
• 用户会话存储，支持滑动过期。
• API 速率限制，防止滥用。
• 需要快速读写临时数据的场景。

限制

• 免费层限制：每月 30,000 条命令，超出可能导致错误。
• 值大小限制：单个值不应超过 1MB，建议小于 100KB。
• 非主数据库：KV 是缓存，不应作为主要数据存储。
• 不支持 Redis Streams：@vercel/kv 不提供流操作方法，需直接使用 @upstash/redis。
• 已知问题：包括环境变量缺失、JSON 序列化错误、键命名冲突、TTL 未设置、类型不匹配、管道错误未处理、扫描操作低效、scanIterator 无限循环、zrange 反向查询返回空数组、Next.js 开发服务器首次调用返回 null、Vite 中 process 未定义、Server Actions 返回陈旧数据等。
• 版本迁移：v3.0.0 中扫描游标类型从数字变为字符串；v2.0.0 默认启用自动管道，并引入 scanIterator 无限循环 bug。

关键规则

• 始终为临时数据设置 TTL（使用 setex 而非 set）。
• 使用命名空间键（如 user:123 而非 123）。
• 处理 null 返回值（键不存在）。
• 批量操作使用管道。
• 不要存储大于 1MB 的值。
• 不要将 KV 作为主数据库。
• 不要存储非 JSON 可序列化的数据。