HGfast Cloud 灵狐加速 · 一站式全球云网络返回首页

Cloudflare D1是什么?从数据库定位到 Workers 入门

更新于 2026-11-16 · hgfastapp.lol

简答:Cloudflare D1 是基于 SQLite 语义的托管无服务器关系型 SQL 数据库,适合用户、订单、文章等结构化数据。判断是否适合,重点看三个信号:是否需要 SQL 关联查询、是否读多写少、单库是否能控制在 10 GB 以内;高频写入、强实时协作或已有 MySQL/PostgreSQL 时,应优先比较其他方案。

定义:Cloudflare D1 是 Cloudflare 面向 Workers 和 Pages 提供的托管、无服务器、基于 SQLite SQL 语义的关系型数据库。

先看结论:D1适合什么项目

以 2026-11-16 核对的官方页面为准,Cloudflare D1 可以理解为“由平台托管、通过 SQL 访问、与 Workers 和 Pages 绑定的 SQLite 风格关系型数据库”。它不是文件存储,也不是简单的键值缓存;用户资料、账户配置、文章、商品、订单、评论等有字段关系的数据,通常更符合 D1 的定位。Cloudflare D1 官方文档将其描述为可从 Workers 和 Pages 项目查询的托管无服务器数据库。

最适合先考虑 D1 的情况包括:需要持久化关系数据;需要用 SQL 做条件筛选、排序、分页或多表查询;应用主要是读请求;应用本身已经部署在 Workers 或 Pages 上;希望减少传统数据库服务器的维护工作。

如果项目有大量持续写入、单库数据会超过 10 GB、要求多个客户端实时协作,或者已经依赖 MySQL/PostgreSQL 的专有能力,就不要只看“能否连接”,还要比较写入路径、数据一致性、迁移成本和现有工具链。

最快判断方法:先把业务数据列成表。如果核心问题是“按用户、订单、文章等条件查询结构化记录”,D1 值得试用;如果核心问题是“存大文件”“缓存键值”“实时协调”或“连接已有 MySQL/PostgreSQL”,应分别比较 R2、KV、Durable Objects 或 Hyperdrive。

Cloudflare D1与SQLite、MySQL、PostgreSQL有什么关系

D1 使用 SQLite 的 SQL 语义,因此熟悉 SQLite 的开发者通常更容易上手。但 D1 是托管数据库产品,不等于把一个本地 SQLite 文件直接上传到服务器。应用一般通过 Workers binding、D1 API 或 Wrangler 对数据库执行操作。

与 MySQL、PostgreSQL 的关系更适合从“兼容性”和“部署位置”理解:D1 面向 Cloudflare Workers 生态;如果你已有 MySQL 或 PostgreSQL 数据库,希望从全球各地的 Worker 访问它,可以查看 Hyperdrive,而不是默认把原数据库迁移成 D1。Cloudflare 的存储选型文档把 Hyperdrive 定义为用于加速 Workers 访问现有 MySQL 和 PostgreSQL 数据库的服务。Cloudflare Workers 存储产品选型文档

D1 的优势是 SQL、关系模型、托管和 Workers 集成;SQLite 本地文件的优势是简单、可离线运行;MySQL 或 PostgreSQL 更适合已有成熟生态、复杂扩展、较大规模或已有运维体系的项目。是否能替代 MySQL,不能只凭数据库名称判断,应逐项核对 SQL 方言、驱动、事务、扩展、连接方式和容量要求。

D1、KV、R2、Durable Objects与Hyperdrive对比

下面的对比用于确定数据模型,不代表所有项目都只能选择一种产品。复杂应用可以组合使用,例如 D1 保存订单关系,R2 保存图片文件,KV 保存低频变化的配置,Durable Objects 处理需要强协调的实时状态。

价格、免费额度与限制:先看哪些数字

D1 的费用按查询使用量、存储和数据库数量计算;官方价格页说明,不按数据库持续运行小时或容量单位收取计算费用,未执行查询时不产生 D1 计算费用。以 2026-11-16 核对的页面为准,Workers Free 的 D1 包含每日 500 万行读取、每日 10 万行写入、账户合计 5 GB 存储和 10 个数据库;Workers Paid 的页面列出每月前 250 亿行读取、前 5000 万行写入、前 5 GB 存储以及每账户前 10 万个数据库为包含量,超出部分按官方页面计费。Cloudflare D1 Pricing

需要特别区分“账户总限制”和“单数据库限制”。官方限制页列出:Workers Paid 单个 D1 数据库最大 10 GB,Free 单个数据库最大 500 MB;账户存储上限分别为 1 TB 和 5 GB;Paid 的 Time Travel 为 30 天,Free 为 7 天;单条查询结果最大 50 MB,官方页面注明该结果大小限制自 2026-11-04 起生效。Cloudflare D1 Limits

D1 单个数据库本身是单线程处理查询,官方文档说明请求过多时可能排队并出现 overloaded 错误。因此,写入频繁的业务不要只依靠增加 Worker 数量来解决;应减少单次请求数量、使用批处理、建立合适索引,并评估是否需要按租户或实体拆分数据库。

价格和配额会随官方页面调整。发布前或正式上线前,应重新打开 Pricing 和 Limits 页面核对,不要把本文数字当成长期不变的报价。

从零创建D1并绑定Workers:最小可执行流程

以下命令中的 <数据库名>、<项目目录> 和 <账号实际值> 都要替换成你的实际内容。官方入门指南要求准备 Cloudflare 账户、Node.js,并通过 CLI 或 Dashboard 创建数据库、定义结构和绑定 Worker。Cloudflare D1 Getting started

  1. 安装或确认 Wrangler:npx wrangler@latest --version。如果项目还不存在,可以先创建一个 Workers 项目,再进入项目目录。
  2. 创建数据库:npx wrangler@latest d1 create <数据库名>。命令返回的 database_id 要保存下来。
  3. 需要主库位置提示时:npx wrangler@latest d1 create <数据库名> --location=apac。location hint 只是期望位置提示,并不保证数据库一定运行在指定位置;如果数据合规要求优先,应在创建时使用 jurisdiction,而不是把 location 当成合规承诺。相关规则见 D1 Data location。
  4. 创建 schema.sql:CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, created_at TEXT NOT NULL);
  5. 先在本地执行:npx wrangler@latest d1 execute <数据库名> --local --file=./schema.sql。
  6. 再执行到远程数据库:npx wrangler@latest d1 execute <数据库名> --remote --file=./schema.sql。不要把只执行了 --local 当成已经修改线上数据库。
  7. 在 Worker 配置中加入 binding:[[d1_databases]] binding = "DB" database_name = "<数据库名>" database_id = "<database_id>"。配置文件格式以当前 Wrangler 项目生成内容为准,保留原有缩进。
  8. 在 Worker 中查询:const result = await env.DB.prepare("SELECT id, name FROM users WHERE id = ?").bind(Number(userId)).first();。如果 userId 来自 URL 或表单,它通常是字符串;示例用 Number() 转换只是为了匹配整数 ID,实际项目仍应校验输入。
  9. 部署并验证:npx wrangler@latest deploy,然后访问 Worker 的测试路由,确认查询返回结果。若本地正常、远程失败,应分别检查 binding 名称、database_id、账户权限和网络连接。

如果使用 Pages Functions,思路仍是创建 D1、配置 binding、通过环境对象访问数据库;具体入口要按当前 Pages 项目结构配置,不要把 Workers 的目录结构原样复制过去。

读复制、数据位置与生产环境注意事项

D1 支持 Time Travel,可按官方页面说明恢复到过去时间点;Paid 页面列出最近 30 天,Free 页面列出最近 7 天。它更适合应对误操作或数据损坏后的恢复,不应替代定期导出、迁移文件和独立备份流程。

D1 Global Read Replication 的重点是读请求:写入仍会转发到主数据库实例,读副本异步接收更新。因此,刚写入后立刻从普通读副本读取时,可能遇到短暂的旧数据;官方文档也说明 Sessions API 可通过 bookmark 提供顺序一致性。D1 Global Read Replication

创建数据库时,location hint 可以提示主数据库实例靠近主要写入来源,但官方明确说明它不保证一定部署在首选位置。若团队分布在多个地区,或主要写入集中在某一地区,应在创建阶段记录选择理由,并用实际请求链路和业务日志验证延迟,而不是把地区名称当成性能保证。

当控制台打不开、Wrangler 远程执行超时、部署后 Worker 无法访问 D1 时,先把问题分层:浏览器打不开可能是本地 DNS、TLS、网络路径或账户页面问题;命令行超时还要检查 Node.js、Wrangler、账户认证和出口网络;Worker 已部署但查询失败,则优先检查 binding、权限、SQL 和数据库状态。网络排查只能帮助定位访问链路,不能替代 D1 日志、查询指标和代码检查。

选择D1前的自查清单

  • 数据是否是用户、订单、文章、商品等结构化关系数据?如果不是,先比较 KV 或 R2。
  • 是否需要 SQL 条件查询、排序、分页、索引或多表关系?如果需要,D1 比键值存储更贴近需求。
  • 单个数据库是否能控制在 10 GB 以内?超过该范围要提前设计拆分,而不是等上线后再迁移。
  • 读请求是否明显多于写请求?如果写入持续高并发,应重点评估 D1 单库单线程和排队行为。
  • 是否需要强实时协作、聊天室或游戏房间状态?这类场景应比较 Durable Objects。
  • 是否已有 MySQL 或 PostgreSQL?优先评估 Hyperdrive 与现有数据库的连接成本。
  • 是否需要存图片、视频、安装包或备份文件?这类非结构化对象通常应比较 R2,而不是把文件内容塞进 D1。
  • 是否记录了 schema、迁移、导出和恢复流程?Time Travel 有帮助,但生产环境仍应保留可重复的数据库变更记录。

如果你的答案是“结构化数据、SQL 查询、读多写少、单库规模可控、应用部署在 Workers 或 Pages”,D1 通常值得做一个小规模验证;如果答案集中在实时协作、超大数据、海量写入或已有传统数据库,则应先做架构对比。

D1与Cloudflare其他数据产品及传统数据库的定位对比

产品或方案数据模型更适合的场景需要注意的地方
D1基于 SQLite 语义的关系型 SQL 数据库用户、订单、文章、商品、账户等结构化数据;读多写少的 Web 应用单库有容量限制;单库写入与查询吞吐需要按业务验证
Workers KV最终一致的键值存储配置、会话、凭据、热门键的高频读取不适合复杂关系查询;写入一致性和写入频率要单独评估
R2S3 兼容的非结构化对象存储图片、视频、备份、静态资源和大对象不是关系数据库;文件元数据可由 D1 保存
Durable Objects带全局唯一实例和事务存储的有状态组件实时协作、聊天室、游戏状态、强协调和数据局部性开发控制力更高,但需要自行设计对象路由和状态模型
Hyperdrive + MySQL/PostgreSQL访问已有传统关系数据库的加速与连接服务已有 MySQL/PostgreSQL,希望由 Workers 访问原数据库数据库仍在原有系统中,需评估网络、权限、SQL 兼容和运维
本地SQLite本地数据库文件桌面工具、测试、离线应用和轻量服务不等于托管数据库;多实例部署、备份和公网访问需自行设计

常见问题

Cloudflare D1免费吗?

有 Free 计划可用于原型和实验,但不是无限免费。以 2026-11-16 核对的官方价格页为准,Free 包含每日读取和写入额度、账户总存储额度以及数据库数量限制;超过每日读写额度后,D1 API 会向客户端返回超限错误,具体数字应以官方 Pricing 和 Limits 页面为准。

Cloudflare D1能替代MySQL或PostgreSQL吗?

部分项目可以迁移,但不能笼统判断。若业务使用标准 SQL、数据规模可控、读多写少,并且主要运行在 Workers 上,D1 可以作为候选;如果依赖 MySQL 或 PostgreSQL 的专有扩展、复杂连接池、较大单库或既有运维体系,应比较迁移成本,也可以评估 Hyperdrive 访问现有数据库。

D1适合做网站数据库吗?

适合一部分网站,例如博客、内容管理、用户资料、商品目录、订单和评论系统。上线前应检查单库容量、查询索引、写入峰值、备份恢复和地区访问路径。图片、视频等大文件不要直接当作关系数据存入 D1,应另行选择对象存储。

D1和SQLite是同一个东西吗?

不是。D1 使用 SQLite 的 SQL 语义,但 D1 是托管、可通过 Workers binding 和 API 访问的云数据库产品;本地 SQLite 通常是应用所在机器上的数据库文件。迁移时仍要检查驱动、文件导入、权限、部署和并发模型。

D1的读复制会不会马上读到刚写入的数据?

不能把普通读复制理解成同步副本。写入仍发送到主数据库,读副本异步接收更新,因此普通读取可能短暂看到旧数据。对写后读取有顺序要求的流程,应根据官方文档评估 Sessions API、bookmark 和业务重试策略。

D1控制台打不开或Wrangler执行超时怎么办?

先区分访问链路和数据库操作:浏览器打不开时检查 DNS、TLS、网络路径和账户登录;Wrangler 超时还要检查 Node.js、Wrangler 版本、认证状态和出口网络;Worker 已部署但查询失败,则检查 binding、database_id、权限、SQL 和日志。不要用 ping 结果单独判断 D1 是否可用。

相关阅读

参考资料

  1. Overview · Cloudflare D1 docs
  2. Getting started · Cloudflare D1 docs
  3. Pricing · Cloudflare D1 docs
  4. Limits · Cloudflare D1 docs
  5. Data location · Cloudflare D1 docs
  6. Global read replication · Cloudflare D1 docs
  7. Choosing a data or storage product. · Cloudflare Workers docs