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;
}

エッジ 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) - メモリリークを防ぎます
名前空間付きのキーを使用する	123 ではなく user:123:profile を使い、衝突を防ぎます
null の戻り値を処理する	存在しないキーは null を返します
バッチ処理にはパイプラインを使用する	1 回の往復でレイテンシを低減できます
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 の型エラー	Zod による検証とともに kv.get<Type>() を使用します
8	パイプラインが失敗しても通知されない	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().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／パイプラインを使用するか、プランをアップグレードします
値の有効期限が切れない	set() ではなく setex() を使用します
JSON のシリアル化エラー	通常のオブジェクトを使用し、BigInt を文字列に変換します

---

トークンの節約：~60%（パターンをリファレンスに抽出） エラーの防止：100%（文書化された問題 10 件すべて） 本番環境で使用する準備ができました！