・Workersで設定やセッションを置きたい
・書いた値が古いまま返る理由を知りたい
・KVとD1のどちらを使うか迷っている
Workers KV は、名前(キー)と中身(値)の組を Cloudflare の中央に保存し、読まれた拠点に写しを置いて返す、Workers 向けの保存先です。読み取りの多い API やサイトを、世界中の利用者に低い遅延で届けるために使います。
この記事では、読み書きの仕組みと反映の時間差、向く用途、料金と無料枠の数え方、D1・Durable Objects との使い分け、始め方を、2026年11月時点の公式ページをもとに説明します。Worker そのものの仕組みは、別の記事に任せます。
この記事のゴール(読了目安 約8分)
書いた値が届く流れと無料枠の数え方を知り、KVに置くか判断できるようになる
Workers KVとは
Workers KV は、データを世界中で保存して取り出せる、キー・バリュー型の保存先です。キーと値の組はネームスペースという箱に入り、ネームスペースは Cloudflare の網に複製されます。
Worker のコードはバインディング(KV を呼ぶための設定)を通して、外のアプリは REST API を通して使います。基本の操作は4つです。
put():書き込みと書き換えget():読み取りlist():一覧。1回に最大1,000キーで、キーの先頭の文字で絞れるdelete():削除
製品ページによると、KV は消えることのあるキャッシュと違い、データを中央の地域に永続的に保存します。
拠点の写しは読み取りを速くするためのもので、元の値は中央に保存されています。
KV は Workers の Free・Paid のどちらのプランでも使えます。Worker そのものの仕組みと無料プランの上限は、Cloudflare Workersとはの記事で説明しています。
読み書きの仕組みと反映の時間差
KV への書き込みは中央の保存先に入り、各拠点へは自動で送られません。読み取りは、読まれた拠点に置いた写し(キャッシュ)から返します。この作りが速さと時間差を生みます。
読み取りの多い使い方では、Worker は利用者に最も近いデータセンターで動きます。その拠点で最初に読むときは写しが無く、近い地域の層、中央の層、中央の保存先の順にたどるので時間がかかります。拠点や地域の写しから返る読み取りをホットリード、中央まで取りに行く読み取りをコールドリードと呼びます。よく読まれる値は、写しが切れる前に裏で取り直されます。

写しを使う分、読み取りは書き込みに対して結果整合(少し時間をおいて全拠点で同じになる性質)です。時間差は次のように出ます。
- 書いた拠点ではふつうすぐ見えますが、保証はありません
- ほかの拠点では、写しが切れるまで60秒以上かかることがあります
- 直前にその拠点で古い値を読んでいると、新しい値が見えるまでさらにかかります
- 「キーが無い」という結果も写しになるので、新しく作ったキーも同じだけ遅れます
KV の値は、読む側の写しが切れるまで古いまま返ることがあります。写しを置く秒数は get() に渡す cacheTtl で決まり、既定は60秒、最小は30秒です。長くするとあまり読まれないキーも速く返せますが、その長さまで古い値が返りえます。公式は、よく書き換え、書いた直後に新しい値を見たいデータには cacheTtl を勧めていません。詳しくは公式のHow KV worksにあります。
向く用途と向かない用途
KV は、書き込みが比較的少なく、速く何度も読む値に向きます。公式が挙げる用途は次のとおりです。
- アプリの設定、機能の切り替え、A/B テストの振り分け
- 許可リスト・拒否リスト
- セッションのデータ、API キーなどの資格情報
- API の応答のキャッシュ、スクリプト・アイコン・JSON などの小さなファイル
公式がセッションや資格情報に KV を勧めるのは、よく読まれ、ほとんど書き換えず、すぐ全体で一致しなくてよいからです。
一方、次の用途には向きません。
- 同じキーを1秒に何度も書き換える(上限は1秒1回で、超えると 429 エラー)
- 途中で割り込まれない更新(原子的な操作)や、1つのトランザクションでの読み書き
- 25MiB を超える値

同じキーに同時に書くと、最後の書き込みが残ります。公式は、1回の実行の中の書き込みを1つにまとめるか1秒以上空け、429 には指数バックオフ(待ち時間を倍々に延ばすやり直し)で対処するよう勧めています。1つのキーに集まる書き込みを複数のキーに散らせるなら、KV でも対応できます。
同じキーを1秒に2回以上書くなら、KV 以外の置き場所を考えます。
キーには、expirationTtl で何秒後に消すかを付けられます(60秒以上。10分後なら600)。期限で消えたキーは保存量の課金に数えません。
料金と無料枠の数え方
かかるのは、読み取り・書き込み・削除・一覧の回数と、保存量・ネームスペースの数の料金です。外へ出ていくデータの転送は無料です。2026年11月時点の公式ページの値を表にしました。
有料プランは Workers Paid(アカウントごとに月5ドルから)で、KV の利用もこれに含まれます。
無料プランでどれか1つの上限を超えると、その種類の操作だけが失敗するようになり、毎日 00:00 UTC(日本時間の午前9時)に戻ります。
回数は次のように数えます。
- 一括読み取りは、読んだキーの数で数える
nullが返る、存在しないキーへの読み取りも入る- 画面(ダッシュボード)や Wrangler で書いた・消した・一覧した分も入る
- REST API の一括書き込みは、書いたキーの数で数える
- 有効期限で消えた分は削除に数えない

存在しないキーを読んでも1回と数えるので、無料枠は思ったより早く減ります。最新の値はKV の料金ページで確かめてください。
D1・Durable Objectsとの使い分け
KV が苦手なことは、次の表のようにほかの保存先に任せます。
表の形のデータを SQL で扱う方法と料金は、Cloudflare D1とはにまとめています。
公式が示す組み合わせは、あるキーへの書き込みをすべて1つの Durable Object 経由にし、読み取りは各 Worker が KV で行う形です。書き込みの後の一致(write-after-write consistency)を得る方法で、読み取りの時間差は残ります。書き込みを1か所に集める仕組みは、Durable Objectsとはで解説しています。
KV には読む速さを任せ、書く正しさが要る部分は Durable Objects に回します。
セッションは KV、ホスティングされたデータベースは Hyperdrive という分け方も、公式の例にあります。既存のデータベースを Workers からつなぐ方法は、Cloudflare Hyperdriveとはで紹介しています。
Workers KVの始め方
公式の Get started は、利用者ごとの通知の設定を保存する例で、次の6段を進めます。
- Worker のプロジェクトを用意する
- KV ネームスペースを作成する(ダッシュボードなら「Create instance」)
wrangler.jsoncのkv_namespacesに、バインディングの名前と ID を書く- Wrangler で値を書いて読む
- Worker のコードで
put()とget()を使う npm run deployで公開する
段1・2・4を Wrangler で進めるコマンドです。
npm create cloudflare@latest -- kv-tutorial
cd kv-tutorial
npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG
npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"
npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text
つまずきやすい点は3つです。
kv key putは既定で手元(ローカル)に書きます。Cloudflare 上のネームスペースに書くときは、末尾に--remoteを付けます- 古い解説にある
kv:namespaceのようなコロンの書き方は、Wrangler 3.60.0 から非推奨です - 新しいプロジェクト向けに Get started が勧める
cf(Cloudflare CLI)は、2026年11月時点でベータです
保存する地域を限りたいときは、Wrangler でネームスペースを作るときに --jurisdiction=eu のように付けます。選べるのは EU・米国・FedRAMP 準拠のデータセンターの3つで、日本はありません。Worker はどこからでも読め、写しは地域の外の拠点にも置かれえます。指定で決まるのは、永続的に保存する場所だけです。
保存地域は後から付けたり変えたりできないので、ネームスペースを作る前に要否を決めます。
よくある質問
書いた値をすぐ全拠点に届けられますか?
標準の KV ではできず、読む側で cacheTtl を最小の30秒にするところまでです。書いた直後の一致が要るなら、公式は Durable Objects を案内しています。小さな設定値をキャッシュの時間を待たずに配る Workers KV Instant は、2026年11月時点で非公開ベータです。
Workersの外からKVを使えますか?
使えます。REST API か Cloudflare の SDK を通します。速さはふつうバインディングが上で、書き込みの回数の制限も REST API のほうが低くなっています。
KVが止まったことはありますか?
2025年6月12日(日本時間13日未明)に KV が使う保存の基盤が止まり、2時間28分の障害が起きました。キャッシュに無い読み取りと書き込みは失敗しましたが、キャッシュにある値は返り、保存したデータにも影響はありませんでした。Cloudflare は、単一の事業者に頼らない形への作業を前倒しすると発表しています。
wrangler devで値がnullになるのはなぜ?
wrangler dev は本番のデータを壊さないよう、既定で手元の KV を使うからです。手元で書いていないキーは null になります。Cloudflare 上のネームスペースを読むには、KV のバインディングの設定に "remote": true を付けます。
この記事のポイント
- KVは中央に保存し、読まれた拠点の写しから速く返す
- 他の拠点で新しい値が見えるまで、60秒以上かかることもある
- 無料枠は書き込み1日1,000回。存在しないキーの読み取りも数える
- 同じキーの頻繁な書き込みはDurable Objects、検索はD1へ
まとめ
Workers KV は読み取りに強い保存先で、元の値は中央に、写しは読まれた拠点に置かれます。別の拠点で新しい値が見えるまでに60秒以上かかる場合もあり、1つのキーに書けるのは1秒に1回です。よく読んでまれに書く設定・セッション・API キーの置き場所に向いています。
始めるなら、Get started の例でネームスペースを作り、--remote を付けて値を書き、読めるかを確かめます。無料枠は書き込みが1日1,000回で、存在しないキーの読み取りも数える点に気を付けます。書いた直後の一致や頻繁な書き込みが要るなら Durable Objects の記事、検索が要るなら D1 の記事へ進んでください。






