跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

调试 D1

最后更新 查看 MarkdownAgent 设置

D1 允许您捕获异常,并记录查询数据库时返回的错误。调试 D1 时,可以使用与调试 Workers 相同的工具。

D1 的 stmt. 和 db. 方法在发生错误时会抛出 Error 对象 ↗。要捕获异常,请记录 e.message 值。

例如,以下代码中的查询包含无效关键字——INSERTZ 而非 INSERT:

try {
    // This is an intentional misspelling
    await db.exec("INSERTZ INTO my_table (name, employees) VALUES ()");
} catch (e: any) {
    console.error({
        message: e.message
    });
}

上述代码抛出以下错误消息:

{
    "message": "D1_EXEC_ERROR: Error in line 1: INSERTZ INTO my_table (name, employees) VALUES (): sql error: near \"INSERTZ\": syntax error in INSERTZ INTO my_table (name, employees) VALUES () at offset 0"
}

错误列表

除了扩展(详细)错误消息外,D1 还返回以下错误常量:

错误消息 描述 建议操作
D1_ERROR 特定 D1 错误的前缀。 请参阅下面的 "List of D1_ERRORs" 了解特定错误的更多详情。
D1_EXEC_ERROR 第 x 行的 Exec 错误:y 错误。
D1_TYPE_ERROR 当列与值之间的类型不匹配时返回。常见原因是提供 undefined 变量(不支持)而非 null。 确保值的类型与列匹配。
D1_COLUMN_NOTFOUND 未找到列。 确保您选择的列存在于数据库中。

下表列出了 D1_ERROR 的具体实例。

D1_ERROR 列表

D1_ERROR 类型 描述 建议操作
No SQL statements detected. 输入查询不包含任何 SQL 语句。 App action: 确保查询包含至少一个有效的 SQL 语句。
Your account has exceeded D1's maximum account storage limit, please contact Cloudflare to raise your limit 账户中所有 D1 数据库的总存储已超过账户存储限制。 App action: 删除未使用的数据库,或将账户升级到付费套餐。
Exceeded maximum DB size. D1 数据库已超过其存储限制。 App action: 从数据库中删除数据行,或将数据分片到多个数据库。
Your account has exceeded D1's free tier daily row read limit. Upgrade to a paid plan or wait until tomorrow (midnight UTC) to continue. See https://developers.cloudflare.com/d1/platform/limits/ for more details. 您的账户已达到 D1 免费套餐的每日行读取限额。 应用操作:等待限额在世界协调时间午夜重置,或将账户升级到付费套餐。请参阅限制。
Your account has exceeded D1's free tier daily row write limit. Upgrade to a paid plan or wait until tomorrow (midnight UTC) to continue. See https://developers.cloudflare.com/d1/platform/limits/ for more details. 您的账户已达到 D1 免费套餐的每日行写入限额。 应用操作:等待限额在世界协调时间午夜重置,或将账户升级到付费套餐。请参阅限制。
D1 DB reset because its code was updated. Cloudflare 已更新 D1(或底层 Durable Object)的代码,包含 D1 数据库的 Durable Object 正在重启。 重试操作。
Internal error while starting up D1 DB storage caused object to be reset. 包含 D1 数据库的 Durable Object 启动失败。 重试操作。
Network connection lost. 影响特定 D1 数据库实例的网络错误。每个 D1 数据库都作为独立的 Durable Object 运行。一个数据库发生中断不会影响帐户中的其他数据库。D1 会自动重试只读查询,最多额外重试两次。写入查询不会自动重试。 重试此操作。对于写入查询,请使用应用层幂等重试逻辑 — 请参阅重试查询。
Replica disconnected from primary. 只读副本与其主实例之间发生网络错误。 重试操作。请参阅上面的 "Retry operation" 说明。
Internal error in D1 DB storage caused object to be reset. 错误导致 D1 数据库重启。 重试操作。
Cannot resolve D1 DB due to transient issue on remote node. 查询无法到达包含 D1 数据库的 Durable Object。 重试操作。请参阅上面的 "Retry operation" 说明。
Can't read from request stream because client disconnected. 发出了查询请求(例如上传 SQL 查询),但在查询完全执行之前连接已关闭。 App action: 重试操作,并确保连接保持打开。
D1 DB storage operation exceeded timeout which caused object to be reset. 查询尝试写入大量信息(例如 GB 级),耗时过长。 App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。
D1 DB is overloaded. Requests queued for too long. 对 D1 数据库的请求排队时间过长,可能是因为请求过多,或排队的请求耗时过长。 App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。
D1 DB is overloaded. Too many requests queued. 对 D1 数据库的请求队列过长,可能是因为请求过多,或排队的请求耗时过长。 App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。
D1 DB's isolate exceeded its memory limit and was reset. 查询加载过多内容到内存,导致 D1 数据库崩溃。 App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。
D1 DB exceeded its CPU time limit and was reset. 查询占用大量 CPU 时间(例如扫描 9 GB 表,或尝试大型导入/导出)。 App action: 将查询拆分为更小的分片。
D1 query result exceeded the maximum response size limit of 50 MB 查询返回的结果超出了 50 MB 的最大查询结果大小。此限制将于 2026-11-04 起执行。 应用操作:只选择所需列,不要使用 SELECT *;或者使用 LIMIT 和 OFFSET 对大型结果集分页。

自动重试

D1 检测只读查询,并在遇到可重试错误导致失败时自动最多重试两次执行这些查询。

D1 确保任何重试尝试不会导致数据库写入,使自动重试不会产生副作用,即使导致修改的查询通过了只读检测。D1 通过在每次查询执行后检查修改来实现这一点,如果重试尝试导致任何写入,查询将被回滚。

查看日志

使用 wrangler tail 或通过 Cloudflare 仪表板 查看 Worker 的实时日志流。

报告问题

在任何错误报告中,您应尽可能包含以下内容:

  • 数据库的 ID。使用 wrangler d1 list 将数据库名称与其 ID 匹配。
  • 遇到问题时运行的查询(或查询)。确保编辑任何个人身份信息(PII)。
  • 执行查询的 Worker 代码,包括使用 Workers Binding API 对 bind() 的任何调用。
  • 完整错误文本,包括 error.cause.message 的内容。

相关资源

D1 绑定超时行为

D1 绑定方法 — run()、all()、first() 和 batch() — 不接受超时选项或 AbortSignal。D1 绑定客户端没有内置的单次调用超时机制。

只要客户端连接保持打开,Workers 处理传入 HTTP 请求就没有墙钟时间限制 — 请参阅 Workers 限制。如果 D1 数据库暂时无法访问,D1 绑定调用会一直阻塞,直到操作完成、达到内部限制,或 Worker 因客户端断开连接等外部事件而终止。

若要限制 Worker 等待 D1 调用的时间,请使用带计时器的 Promise.race:

const timeout = new Promise((_, reject) =>
  setTimeout(() => reject(new Error('D1 call timed out')), 5000)
);
const result = await Promise.race([
  db.prepare('SELECT 1').first(),
  timeout,
]);

这篇文档对您有帮助吗?