我該用哪種儲存？KV / D1 / R2 / Durable Objects / Hyperdrive 選型

Cloudflare 提供五種差很多的資料儲存方式，它們全都掛在你的 Worker 後面。選錯會讓一切變難；選對則讓程式碼又短又快。這份指南把「該用哪個」變成幾個是/否的問題。

先把所有角色擺上同一個舞台：Worker 是大腦，每種儲存各演一個角色。KV 是快取、D1 是 SQL 資料表、R2 是檔案櫃、Durable Objects 是「唯一真相來源」、Hyperdrive 是通往你既有資料庫的快速通道。

從最上面開始，照著答案往下走，每條分支都會落在一個產品上。之後你當然可以混搭多種儲存，但對「單一一筆資料」來說，這棵樹會給你一個明確的預設答案。

每個儲存一張卡片，附上「什麼時候該用它」的一句話原則。

「binding（綁定）」是你在 wrangler.jsonc 宣告的一個名字，它會以 env.某某 的形式出現在 Worker 裡。下面是每種儲存最小的真實片段——注意它們的存取方式差很多。

1. KV — 讀取 / 寫入一個值

   用 key 查找；值是字串（或串流）。可選的 TTL 會讓 key 自動過期。

   jscontent_copy複製

   // wrangler.jsonc -> { "kv_namespaces": [{ "binding": "KV", "id": "..." }] }
   const cached = await env.KV.get("user:42");
   await env.KV.put("user:42", JSON.stringify(user), { expirationTtl: 3600 });

2. D1 — 預備式 SQL 查詢

   用 ? 佔位符寫 SQL，用 bind() 填值，再用 .all() 取回資料列。

   jscontent_copy複製

   // wrangler.jsonc -> { "d1_databases": [{ "binding": "DB", "database_name": "app" }] }
   const { results } = await env.DB
     .prepare("SELECT * FROM orders WHERE city = ?")
     .bind("Taipei")
     .all();

3. R2 — 存入 / 取出一個物件

   用 put() 以 key 存檔，再用 get() 取回一個物件，它的 .body 是串流。

   jscontent_copy複製

   // wrangler.jsonc -> { "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "files" }] }
   await env.BUCKET.put("invoice.pdf", request.body);
   const object = await env.BUCKET.get("invoice.pdf");
   return new Response(object.body);

4. Durable Objects — 呼叫 stub

   getByName() 會回傳「那個名字唯一的一個實例」；直接用 RPC 呼叫它的方法。所有呼叫者都打到同一個物件。

   jscontent_copy複製

   // wrangler.jsonc -> durable_objects: { "name": "ROOM", "class_name": "Room" }
   const stub = env.ROOM.getByName("room-42");
   const count = await stub.increment(); // strongly consistent

5. Hyperdrive — 連線字串

   讀取 env.HYPERDRIVE.connectionString，用一般的 pg 客戶端連線；連線池與快取都自動幫你處理。

   jscontent_copy複製

   // wrangler.jsonc -> { "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "..." }] }
   import { Client } from "pg";
   
   const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
   await client.connect();
   const { rows } = await client.query("SELECT * FROM products LIMIT 10");

大多數的選擇其實是被三個概念決定的：一致性、關聯式 vs 鍵值、以及物件儲存。搞懂它們，那棵決策樹就一目了然。

什麼時候用哪個…

• 用 KV：小資料讀遠多於寫，且約 60 秒的全球同步可接受（快取、設定、工作階段）。
• 用 D1：需要關聯式資料表與 SQL 查詢（JOIN／WHERE／ORDER BY），且想要 Cloudflare 原生資料庫。
• 用 R2：要存大型檔案——圖片、影片、PDF、備份——而且想要零 egress 流量費。
• 用 Durable Objects：某一份共享狀態必須強一致且需要協調（計數器、聊天室、鎖）。
• 用 Hyperdrive：你已在別處跑 Postgres／MySQL，只想讓它從 Workers 連起來變快——不用搬遷。

• KV：讀多寫少、最終一致、只有鍵值、單筆最多 25 MiB。
• D1：以 SQLite 為基礎的關聯式 SQL、有讀取副本，是應用資料的好預設。
• R2：相容 S3 的物件儲存、無 egress 流量費，最適合媒體與備份。
• Durable Objects：一個名字對應一個實例、強一致、內建自己的 SQLite。
• Hyperdrive：在你既有 Postgres／MySQL 前面加上連線池與快取——它不是一個新資料庫。