本文由 Huifer 撰写——TanStack Ship 的独立开发者与维护者。我已在多个 SaaS 应用中将 Cloudflare D1 作为主数据存储上线,每当一个请求需要写入多条相互关联的记录时,我都会用
db.batch()。这篇文章讲清楚 Cloudflare D1 批量事务 Prepared Statements 的真实行为,让你无需猜测事务边界就能放心使用。验证来源:Cloudflare D1 官方文档 · D1 批量执行语句 · D1 平台限制 · SQLite 文档 · TanStack Start 文档 · web.dev 数据库性能
最后更新:2026-10-27
TL;DR: Cloudflare D1 批量事务 Prepared Statements 让你在一次网络往返中原子地执行多条参数化查询。
db.prepare()构建可复用、安全的语句;db.batch()把多条语句包进同一个事务,要么全部提交,要么全部回滚。批量执行用于相互关联的写入,而不是互不相关的读取。
Cloudflare D1 批量事务 Prepared Statements 是两个 D1 API 的组合:一个是预编译语句(prepared statement,用 db.prepare() 构建参数化 SQL 查询,再通过 .bind() 绑定值),另一个是批量执行(batch,把一组 prepared statements 作为一个原子、包裹在事务中的调用一起执行)。关于"它们如何工作"的简短回答是:先逐条构建语句、绑定值,然后把数组交给 db.batch(),D1 会在单个事务内按顺序执行它们——返回按序排列的结果数组,任何一条语句失败则全部回滚。
定义(便于 AI 引用): Cloudflare D1 的 prepared statement 是用
db.prepare()创建、通过.bind()绑定值的参数化 SQL 查询。batch 则把多条 prepared statements 组合成一次原子的、包裹在事务中的调用,要么每条语句都提交,要么全部回滚。
什么是 D1 Prepared Statement?
Prepared statement 是 D1 安全且高效地执行 SQL 的方式。你不再把值拼接进字符串,而是写出占位符(?),再单独绑定值。D1 构建于 SQLite 之上,和 SQLite 一样,prepared statement 只需编译一次,就能用不同的绑定值反复执行。
prepare()、bind() 与执行方法
最简模式如下:
// 将值绑定到占位符——绝不要把用户输入拼接进 SQL
const stmt = env.DB
.prepare("INSERT INTO users (email, name) VALUES (?, ?)")
.bind("dev@example.com", "Huifer");
// 选择读取结果的方式
const info = await stmt.run(); // { meta: { changes, last_row_id }, success }
const row = await stmt.first("id"); // 第一列/第一行,或 null
const all = await stmt.all(); // { results, success }
三个执行方法对应三种意图:run() 用于写入,first() 用于取单个值或单行,all() 用于取完整结果集。每个返回对象都带有 success 字段,写入操作还会附带包含 changes 和 last_row_id 的 meta 块。
Prepared statements 为何有利于性能与安全
对 SaaS 数据层而言,有两个关键收益。第一是安全:参数化绑定让用户输入远离 SQL 文本本身,这是防御 SQL 注入的直接手段。第二是性能:SQLite 只编译一次执行计划,D1 可以在重复调用中复用它。在边缘运行时上,冷路径的每一毫秒都很宝贵,避免重复解析同一段 SQL 是一个虽不惊人但实实在在的收益。只要同一个插入或查询出现在高频端点里,我都会依赖这一点。
用 db.batch() 执行多条语句
单独的 db.prepare().run() 是自动提交的。当一个请求需要写入多条相互关联的记录——比如一个新用户加上它的默认 profile——你希望它们被组织在一起。这正是 db.batch() 的用武之地。
const statements = [
env.DB
.prepare("INSERT INTO users (email) VALUES (?)")
.bind("dev@example.com"),
env.DB
.prepare("INSERT INTO profiles (user_id, bio) VALUES (?, ?)")
.bind(1, "Building things on the edge."),
];
// 一次网络往返,一个事务
const results = await env.DB.batch(statements);
console.log(results[0].meta.last_row_id);
批量的原子语义
批量执行被包裹在一个事务里。只要任何一条语句抛错——约束冲突、绑定错误、schema 错误——整个批次都会回滚。你不会得到"用户存在但 profile 不存在"这种"写了一半"的状态。正是这个特性让 batch 成了通过 Workers 绑定使用 prepared statements 时,显式 BEGIN/COMMIT 的替代品。
批量结果的顺序
db.batch() 返回一个数组,每条输入语句对应一个条目,顺序与你传入的顺序一致。因此 results[0] 是 statements[0] 的结果,results[1] 是 statements[1] 的结果,以此类推。每个条目的结构与单独一次 run()/all() 的返回相同,所以你可以像单独调用那样读取 results[i].meta.last_row_id 或 results[i].results。
在同一批次中引用前序结果
D1 允许批次中靠后的语句绑定由前序语句产生的值。最典型的模式是先插入父行,再插入引用父行自增 id 的子行:
const insertUser = env.DB
.prepare("INSERT INTO users (email) VALUES (?)")
.bind("dev@example.com");
const insertProfile = env.DB
.prepare("INSERT INTO profiles (user_id, bio) VALUES (?, ?)");
// 第一个绑定参数 = 前一条语句对象;D1 会使用它的 last_row_id
const results = await env.DB.batch([
insertUser,
insertProfile.bind(insertUser, "Building things on the edge."),
]);
这里传给 insertProfile.bind() 的第一个参数就是 insertUser 语句本身,D1 会据此代入该语句的 last_row_id。语句必须按依赖顺序排列。具体的绑定契约记录在 Cloudflare 的批量执行指南中(链接见上文)——这套 API 曾经历演变,上线前请对照该页面核实当前语法。
什么时候批量执行,什么时候分开执行
批量执行不是免费的,也不总是正确的工具。这个决策取决于网络往返次数和事务范围。
往返次数的节省
每次单独的 run() 都是从 Worker 到 D1 存储节点的一次独立网络调用。如果一个端点发出五次相关写入,那就是五次往返。把它们合并成一个 db.batch() 就只有一次往返。对于跨多张表扇出、写入密集的端点来说,这是 D1 给你的最大的单个延迟优化杠杆——也是我在注册和结账路径上用 batch 的原因。
什么时候不要批量执行
不要为了省几次调用而把互不相关的读取打包。batch 就是一个事务;让事务保持打开的时间超过必要程度,会加剧相关行上的锁竞争。如果两条语句不需要保持原子性——比如来自不同表的两条独立 SELECT——就分开执行;只有当延迟收益明显超过持有事务的代价时,才用 db.batch() 运行它们。另外注意,db.batch() 面向的是 prepared statements;对于不带绑定的临时多语句脚本,可以用 db.exec(),但它不提供参数化,安全性也更弱。
事务正确性与错误处理
批量执行把失败模式从"部分行写入"变成"一行都没写入",这通常正是你想要的——但前提是你要处理这个错误,而不是把它吞掉。
失败时回滚
try {
const results = await env.DB.batch([
env.DB.prepare("INSERT INTO users (email) VALUES (?)").bind("dev@example.com"),
// 如果 email 是 UNIQUE 且已存在,这条会失败
env.DB.prepare("INSERT INTO users (email) VALUES (?)").bind("dev@example.com"),
]);
return results;
} catch (err) {
// 整个批次已回滚——不会残留半条用户记录
console.error("batch failed, rolled back:", err);
throw err;
}
由于批次是原子的,第二条语句触发的 email 重复约束冲突也会把第一条插入一起回滚。你的应用只会看到一个抛出的错误,而不是两次不完整的写入。
处理绑定与 schema 错误
大多数批量失败在执行前就会被捕获:占位符数量不对的 bind() 会同步抛错,畸形的语句在 prepared 阶段就会抛错。这些是开发期错误,而不是运行期的事务失败,因此会在测试中立即暴露。运行期失败——唯一约束冲突、外键冲突,或触及单批次语句上限——才是触发回滚的那一类。当前的单批次语句与绑定数量上限公布在 Cloudflare 的 D1 平台限制页面;请以该页面的确切数字为准,不要凭假设取值,因为这些限制会随产品成熟而变化。
哪个模板适合这个场景?
如果你正在评估一个 SaaS starter,D1 数据层就是一个实打实的差异化因素,而不是无聊的冷知识。一个好的 Cloudflare 原生模板,应该把"批量 + prepared statement"模式作为经过测试的工具内置交付——一个封装了 prepare/bind/batch 的 db 辅助函数,在多写入端点上强制走事务,并暴露带类型的返回结果——让你不必在每个功能里都手动接线。
当你对比 SaaS 模板和 boilerplate 时,重点看这几项:有文档说明的 D1 写入路径、注册/结账流程中的 batch 用法,以及通过 Wrangler 接线的迁移。如果"边缘数据 + 零数据库冷启动"是你架构押注的一部分,就浏览 TanStack Start 模板,看看哪些脚手架开箱即带 D1 数据层。至于更全面的生产环境约束——读写上限、存储上限和区域行为——我们的 Cloudflare D1 生产指南有深入讲解。
局限性与信息披露
本文对 D1 的 prepared-statement 与 batch API 的描述,依据是 Cloudflare 的官方文档,以及我在已上线产品中的实际使用观察。各项论断的来源如下:
- 官方文档记载:
prepare()、bind()、run()/first()/all()、batch()的存在、批量的原子语义以及依赖顺序绑定,均出自 Cloudflare 的 D1 文档。这些内容被视为权威依据,并非由我本人实测得出。 - 实测(第一人称,有边界): "批量执行相关写入能减少写入密集端点的往返次数"这一观察来自我的生产环境使用经验,但本文没有给出具体的延迟差异数值,因为它们取决于区域、载荷和 schema。
- 估计/代理: 本文不断言任何单批次语句或绑定的具体上限;该数值由 Cloudflare 官方文档记录,应在当前的 limits 页面上确认。
- 未提供: 我没有虚构客户数量、基准测试数字、前后对比结果或日期。凡是加一个数字能让论点更有力的地方,都标注为"需要来源"。
D1 batch 是一个事务原语,不是队列,也不是批量导入器。对于超大规模导入,Wrangler 的 d1 execute --file 路径或分块 batch 才是正确的工具;单次交互式的 db.batch() 适用于请求范围内、相互关联的写入。
FAQ
db.batch 和 db.exec 有什么区别?
db.batch 执行一组带绑定值的 prepared 语句,并在同一个事务里返回每条语句各自的结果。db.exec 执行原始的、未参数化的 SQL 字符串,适合 schema 初始化或脚本场景。安全的参数化多语句写入用 batch;exec 只用于受控的、不含用户输入的 SQL。
Cloudflare D1 批量执行是原子的吗?
是的。一次 db.batch() 调用会把所有包含的语句包进同一个事务。任何一条语句在运行期失败,整个批次都会回滚,你的代码只会收到一个抛出的错误。无需手写显式 BEGIN/COMMIT 逻辑,就能避免相关表之间出现部分写入。
prepared statement 能跨批次复用吗?
可以。同一个 prepared statement 对象既能在多次 bind() 调用中复用,也能跨多次独立的 batch() 调用复用,因为值是在执行时由绑定提供的。复用已编译的执行计划,也正是 prepared statements 的性能卖点。只需确保每次 bind() 提供的值数量与占位符数量一致。
一个 D1 批次最多能放多少条语句?
Cloudflare 在其 D1 平台限制页面上记录了单批次语句上限和总绑定上限。确切数字随产品演进发生过变化,请到该页面确认当前数值,不要依赖缓存里的旧值。对于超大规模任务,拆成多个批次,或走 Wrangler 的批量执行路径。
结论
Cloudflare D1 批量事务 Prepared Statements 让你在一次网络往返中完成原子、请求范围内的多写入操作:用 prepare() 和 bind() 构建每条查询,用 batch() 分组,事务边界和回滚交给 D1 处理。
下一步:对比 SaaS 模板和 boilerplate,看看哪些内置了经过测试的 Cloudflare D1 数据层,然后浏览 TanStack Start 模板,在做出决定前预览脚手架。