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:什麼時候用鍵值儲存?
await env.CONFIG.put("site:banner", "雙十一優惠中", { expirationTtl: 86400 });
const banner = await env.CONFIG.get("site:banner");
KV 寫入後需要一段時間才同步到全球,不適合需要立即讀到最新值的資料(例如庫存數量、計數器)。
D1:什麼時候用 SQL 資料庫?
建立資料表(寫成 SQL 檔再執行):
schema.sql
CREATE TABLE IF NOT EXISTS posts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
created_at TEXT DEFAULT CURRENT_TIMESTAMP
);
在程式中查詢,一律使用 bind() 帶入參數,避免 SQL Injection:
const { results } = await env.DB
.prepare("SELECT id, title FROM posts WHERE id = ?")
.bind(postId)
.all();
省略 --remote 時指令作用在本機開發用的資料庫,方便測試而不影響正式資料。
R2:什麼時候用物件儲存?
// 上傳
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 儲存。