跳轉至

建立 2026-11-22 更新 2026-11-22

KV、D1 與 R2

Cloudflare 提供三種最常用的儲存服務給 Workers 與 Pages Functions 使用:KV 是全球分散的鍵值儲存,適合讀多寫少的資料;D1 是以 SQLite 為基礎的 SQL 資料庫,適合需要查詢與關聯的結構化資料;R2 是相容 Amazon S3 的物件儲存,適合存放圖片、影片等檔案,而且下載流量不收費。本頁說明三者的差異、選用時機與基本用法。

三者該怎麼選?

KV D1 R2
資料形式 鍵 → 值(字串、JSON、二進位) 資料表(SQL) 檔案(物件)
強項 全球讀取極快 查詢、排序、關聯 大檔案、便宜、無流出費
寫入一致性 最終一致(其他地區最多約 60 秒才看到) 強一致 強一致
典型用途 設定、快取、短網址對照 會員、文章、訂單 圖片、影音、備份

簡單判斷:要查詢用 D1,存檔案用 R2,單純用 key 讀值且很少更新用 KV。

如何綁定儲存服務?

所有服務都透過綁定(Binding)提供給程式:在 wrangler.jsonc 宣告後,程式中就能用 env.<名稱> 存取,不需要連線字串或金鑰。

wrangler.jsonc
{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2026-11-01",
  "kv_namespaces": [{ "binding": "CONFIG", "id": "<KV_ID>" }],
  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "<D1_ID>" }],
  "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-files" }]
}

KV:什麼時候用鍵值儲存?

npx wrangler kv namespace create CONFIG
await env.CONFIG.put("site:banner", "雙十一優惠中", { expirationTtl: 86400 });
const banner = await env.CONFIG.get("site:banner");

KV 寫入後需要一段時間才同步到全球,不適合需要立即讀到最新值的資料(例如庫存數量、計數器)。

D1:什麼時候用 SQL 資料庫?

npx wrangler d1 create my-db

建立資料表(寫成 SQL 檔再執行):

schema.sql
CREATE TABLE IF NOT EXISTS posts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
);
npx wrangler d1 execute my-db --remote --file=./schema.sql

在程式中查詢,一律使用 bind() 帶入參數,避免 SQL Injection:

const { results } = await env.DB
  .prepare("SELECT id, title FROM posts WHERE id = ?")
  .bind(postId)
  .all();

省略 --remote 時指令作用在本機開發用的資料庫,方便測試而不影響正式資料。

R2:什麼時候用物件儲存?

npx wrangler r2 bucket create my-files
// 上傳
await env.FILES.put("avatars/alice.png", request.body, {
  httpMetadata: { contentType: "image/png" },
});

// 下載
const obj = await env.FILES.get("avatars/alice.png");
if (!obj) return new Response("Not found", { status: 404 });
return new Response(obj.body, {
  headers: { "content-type": obj.httpMetadata?.contentType ?? "application/octet-stream" },
});

R2 也能用一般 S3 工具(AWS CLI、rclone)透過 S3 相容 API 存取,在 R2 頁面建立 API Token 即可。若要讓檔案直接公開下載,可以在 Bucket 設定綁定自訂網域(例如 files.example.com)。

R2 最大的優勢:無流出費用

多數雲端儲存會對下載流量(Egress)收費,網站流量一大就很可觀。R2 只收儲存空間與操作次數費用,下載流量免費,免費方案每月含 10 GB 儲存。

相關資料