Cloudflare 儲存完全指南：D1 / R2 / KV

💡 免費起步：D1、R2、KV 都有免費方案、免信用卡即可使用；R2 更是資料流出零費用（zero egress）。實際操作見 快速開始。

目錄

• 三種儲存怎麼選？
• 快速開始（免費）
• D1：Serverless SQLite
• R2：S3 相容物件儲存
• KV：鍵值儲存
• 三者對照表
• 與 Workers / Pages 整合
• 最佳實踐
• 常見問題
• 總結

三種儲存怎麼選？

三者解決的是不同的資料形態，並非彼此替代品，常見的做法是同一個應用同時使用多種。先用需求對應到產品，再深入各自細節。

判斷順序可以簡化為：要查詢就用 D1、放大檔案就用 R2、簡單取值就用 KV。

快速開始（免費）

三種資源都透過 wrangler CLI 建立，並在 Workers/Pages 的 wrangler.toml 中宣告 binding 後存取。先安裝與登入：

npm install -g wrangler
wrangler login

接著各自建立資源（指令細節見後續章節）：

# D1：建立資料庫
wrangler d1 create my-database

# R2：建立 bucket
wrangler r2 bucket create my-bucket

# KV：建立 namespace
wrangler kv namespace create MY_KV

每個指令會回傳對應的 ID 或設定片段，貼回 wrangler.toml 即完成綁定。免費方案不需信用卡即可使用，額度細節以官方文件為準。

D1：Serverless SQLite

是什麼

D1 是 Cloudflare 託管的 Serverless SQLite 資料庫，跑在邊緣網路上，使用標準 SQL 操作。底層即 SQLite，因此 SQLite 的 SQL 語法、型別親和性（type affinity）等觀念通用，可參考 SQLite 筆記。

核心特性

• 關聯式查詢：支援資料表、index、JOIN、交易等 SQL 能力。
• Serverless：不需自行管理資料庫伺服器，依用量計費，免費方案有額度。
• 以 binding 存取：在 Worker/Pages 中透過 env.DB 之類的綁定取得資料庫物件。

適用情境

• 應用的關聯式主資料（使用者、訂單、文章等需要查詢與關聯的結構化資料）。
• 需要 SQL 聚合、篩選、排序的查詢場景。
• 取代「為了存結構化資料而硬塞進 KV」的不合適做法。

免費額度

數字以官方文件為準。

範例

建立資料庫並執行 schema：

# 建立資料庫，會回傳 database_id
wrangler d1 create my-database

# 在本機或遠端執行 SQL
wrangler d1 execute my-database --command "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"

在 wrangler.toml 宣告 binding：

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "<從 create 指令取得的 id>"

在 Worker 中透過 binding 查詢：

export default {
  async fetch(request, env) {
    const { results } = await env.DB
      .prepare("SELECT id, name FROM users WHERE id = ?")
      .bind(1)
      .all();
    return Response.json(results);
  }
};

R2：S3 相容物件儲存

是什麼

R2 是 Cloudflare 的物件儲存，提供與 Amazon S3 相容的 API，可用既有的 S3 SDK 與工具對接，也可透過 Worker binding 直接讀寫。

最大賣點：零 egress 費用

R2 的主要差異化在於資料流出（egress）零費用：把資料讀出傳給使用者不另計費。相對地，AWS S3 對資料流出收取 egress 費用，當對外流量大時（例如圖片或影片大量被讀取），這部分成本可能相當可觀。對流量導向的場景，零 egress 是 R2 與 S3 的主要成本差異來源。

適用情境

• 圖片、影片等媒體檔案。
• 備份檔、匯出檔等大型物件。
• 網站的大型靜態資產（下載檔、資料集等）。

免費額度

數字以官方文件為準。

範例

建立 bucket：

wrangler r2 bucket create my-bucket

在 wrangler.toml 宣告 binding：

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

在 Worker 中綁定讀寫：

export default {
  async fetch(request, env) {
    // 寫入物件
    await env.MY_BUCKET.put("hello.txt", "world");

    // 讀取物件
    const object = await env.MY_BUCKET.get("hello.txt");
    if (object === null) {
      return new Response("Not Found", { status: 404 });
    }
    return new Response(object.body);
  }
};

若要沿用既有工具，也可使用 S3 相容 SDK，將 endpoint 指向 R2 的 S3 相容位址，搭配 R2 的存取金鑰操作。

KV：鍵值儲存

是什麼

KV（Workers KV）是最終一致（eventually consistent）的全球鍵值儲存，把資料散布到全球節點，讀取延遲低。設計上適合讀多寫少的場景。

適用情境

• 應用設定、環境參數。
• 特徵旗標（feature flags）。
• 快取資料。
• Session 等可容忍短暫不一致的鍵值。

注意事項

• 最終一致性：寫入後在全球節點間傳播需要時間，短時間內不同地區可能讀到舊值。需要即時一致的資料不適合放 KV。
• 寫入額度低：免費方案每日寫入次數遠低於讀取，KV 不適合高頻寫入或把它當成關聯式資料庫使用。

免費額度

數字以官方文件為準。

範例

建立 namespace：

wrangler kv namespace create MY_KV

在 wrangler.toml 宣告 binding：

[[kv_namespaces]]
binding = "MY_KV"
id = "<從 create 指令取得的 id>"

在 Worker 中綁定讀寫：

export default {
  async fetch(request, env) {
    // 寫入鍵值
    await env.MY_KV.put("feature_flag", "on");

    // 讀取鍵值
    const value = await env.MY_KV.get("feature_flag");
    return new Response(value ?? "not set");
  }
};

三者對照表

與 Workers / Pages 整合

三種儲存都透過 bindings 與運算層整合，概念一致：

1. 用 wrangler CLI 建立資源，取得 ID 或設定片段。
2. 在 wrangler.toml 中宣告對應的 binding 區塊（d1_databases、r2_buckets、kv_namespaces）。
3. 在程式中以 env.XXX 存取，名稱對應 binding 的 binding 欄位。

這個模式同時適用於 Cloudflare Workers 與 Cloudflare Pages（Pages Functions）。使用 binding 的好處是不必在程式中硬寫憑證或連線字串，存取由平台注入，憑證不進入原始碼。

# 同一個 wrangler.toml 可同時宣告多種儲存
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "<id>"

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

[[kv_namespaces]]
binding = "MY_KV"
id = "<id>"

最佳實踐

• 依資料特性選對儲存：關聯式結構化資料用 D1、大型檔案用 R2、簡單鍵值用 KV，不要把結構化資料硬塞進 KV，也不要把大型檔案塞進資料庫。
• KV 注意最終一致與寫入限制：把 KV 用在讀多寫少、可容忍短暫不一致的資料；需要即時一致或高頻寫入時改用 D1。
• R2 善用零 egress 放大型資產：對外流量大的媒體與下載檔放 R2，egress 不計費可降低流量成本。
• D1 當關聯式主資料：需要查詢、關聯與交易的資料以 D1 為主，沿用 SQLite 的 SQL 觀念。
• 用 bindings 而非硬寫憑證：在 wrangler.toml 宣告綁定、以 env.XXX 存取，避免把金鑰寫進程式碼。

常見問題

D1 跟一般 SQLite / Postgres 差在哪？

D1 底層就是 SQLite，因此 SQL 語法與型別親和性等觀念與一般 SQLite 通用；差別在於它是 Cloudflare 託管的 Serverless 服務，跑在邊緣、依用量計費、以 binding 存取，不需自行架設資料庫伺服器。相較 Postgres，SQLite 在型別系統與部分進階功能上較精簡，選用時以實際查詢需求為準。

R2 為什麼比 S3 省錢（egress）？

R2 對資料流出（egress）零費用，而 AWS S3 會對資料流出收取 egress 費用。當對外流量大時（例如媒體檔案大量被讀取），S3 的 egress 成本會明顯累積，R2 在這部分不另計費。儲存與操作次數仍各有計費規則，整體成本以實際用量與官方定價為準。

KV 的最終一致會有什麼問題？

寫入 KV 後，新值在全球節點間傳播需要時間，期間不同地區可能讀到舊值。因此 KV 不適合需要「寫入後立刻一致」的資料（如即時餘額、強一致狀態）。這類資料應改用 D1。

三個我該用哪個？

依資料形態決定：要 SQL 查詢與關聯選 D1、放大型檔案選 R2、存簡單鍵值（設定/旗標/快取/Session）選 KV。可參考前面的 三種儲存怎麼選？ 決策表。

可以同時用嗎？

可以。三者是互補產品，同一個 Worker 或 Pages 應用可同時宣告 D1、R2、KV 的 binding 並各自存取，例如用 D1 存主資料、R2 存使用者上傳的檔案、KV 存設定與快取。

總結

核心要點

D1  → Serverless SQLite，關聯式 SQL，當主資料庫
R2  → S3 相容物件儲存，零 egress，放大型檔案
KV  → 最終一致鍵值儲存，讀多寫少，放設定/快取
整合 → 一律用 wrangler 建資源 + wrangler.toml 宣告 binding + env.XXX 存取

選用決策樹

要存什麼？
├─ 結構化、要查詢/關聯 ─────► D1（SQL）
├─ 大型檔案/媒體/備份 ──────► R2（零 egress）
└─ 簡單鍵值（設定/旗標/快取）
     ├─ 讀多寫少、可容忍短暫不一致 ─► KV
     └─ 需要即時一致或高頻寫入 ─────► D1

免費額度速查表

數字以官方文件為準。

記憶口訣

查詢用 D1、檔案用 R2、取值用 KV；流量大別忘了 R2 零 egress、寫入多別用 KV。

系列總覽：Cloudflare 開發者平台總覽

建立日期：2026-06-08 最後更新：2026-06-08