D1 查询结果限额何时生效
Cloudflare 在 2026 年 10 月 30 日发布公告:D1 从 11 月 4 日起执行单次查询结果最大 50 MB 的限制,超出后返回错误;通过 REST API 进行的导入、导出操作不受这项限额影响。本文发布于 10 月 31 日,因此这是即将生效的变化,不能写成所有请求已经受到限制。官方公告
这次调整最值得检查的是管理后台、报表、同步脚本和历史数据下载。它们可能平时访问很少,却在某个大客户或月底任务中一次取回大量记录。下面的改造顺序属于工程建议,并非 Cloudflare 要求所有应用照搬的迁移步骤。
不要把结果大小等同于数据库容量
结果限额约束一次查询返回的数据,并不表示数据库只能保存同样大小的内容。官方限制页也分别列出数据库大小、单行大小、查询时间和查询结果大小。排查时应先确认命中了哪一种边界,避免把一个结果集问题误诊为存储空间不足。D1 限制文档
先找出会膨胀的接口
从业务动作追到 SQL
列出“全部导出”“加载所有成员”“拉取完整历史”等入口,再追踪对应查询。不能只搜索没有 LIMIT 的语句:一条带行数限制的查询,也可能因为正文、附件元数据或大段 JSON 而返回过多字节。反过来,行数很多的窄表未必就是最大风险。
建议为每个候选接口记录筛选范围、返回字段、常见与最大样本、触发者、调用频率。日志保留查询模板标识、耗时和结果体积等指标即可,不要为测大小把用户内容完整写入日志。应用层序列化后的字节数可作为观测信号,但没有核对服务端计量口径前,不应把它当成精确的限额判定值。
为列表和详情划分字段
列表只返回展示、排序和定位所需字段。用户展开详情时,再读取正文或其他较大的数据。改动 SQL 后也要收紧接口响应类型,删除前端对旧字段的隐式依赖;否则一次看似简单的字段裁剪,会把故障转移到页面渲染。
可以从一个最重的列表开始,比较改造前后的响应大小、首屏时间和数据库耗时。为接口设置自己的合理预算,留出字段增长余量;不必等到逼近平台上限才采取行动,也不要把本文中的任何示例页大小当成通用安全值。
分页需要同时设计排序与一致性
小列表可以先采用偏移分页
官方公告建议减少选择列,并使用 LIMIT 与 OFFSET 分页。对规模较小、需要直接跳页的后台,这通常是容易理解的起点。不过,分页必须有确定排序;仅按可能重复的时间字段排序,遇到同一时间的多条记录时,页面边界可能不稳定。公告中的处理建议
长列表评估游标方案
SQLite 官方文档说明,较大的 OFFSET 会先处理再丢弃前面的结果,随着偏移增加,工作量也会增长;在适当索引下,记住上一页末尾位置并使用行值比较,可以更高效地继续读取。SQLite 滚动窗口查询
工程上可选择创建时间与唯一 ID 作为复合位置,但必须让查询条件、排序方向和索引一致。排序键能否为空、是否会被修改,也要提前约定。游标中携带筛选条件版本或范围信息,服务端仍重新验证访问权限,不能把一个可解析的游标当作授权凭证。
游标分页也不自动提供跨多次请求的快照。如果遍历期间有人修改排序字段,仍可能重复或漏项。展示型列表可以接受“刷新获取最新”的语义;对账或完整导出则需要另行明确数据时间边界、去重键和一致性要求,不能把连续翻完几页直接等同于取得某一时刻的全量数据。
分页之后仍要检查扫描量
只返回几十行,不代表只读取几十行。D1 的索引指南建议用 EXPLAIN QUERY PLAN 检查访问计划,结合实际查询选择索引。应同时观察扫描行数和返回行数,避免响应变小了,后台仍反复扫描整张表。D1 索引指南
大型导出走独立流程
区分数据库备份与用户报表
REST 导入导出不受本次结果限额影响,不等于它适合直接作为任意用户的下载接口。官方导出文档还提示,运行中的导出会阻塞其他数据库请求。全库备份与经过权限过滤的业务报表,应分别评估执行时机和影响。导入导出文档
业务报表可考虑异步分段读取、生成文件、保存任务进度,再向原申请者提供受控下载。每段失败应能从已确认位置恢复,并保证重复处理不会重复写入。完成标志要在行数核对和文件关闭后写入,避免用户拿到一个实际上还未生成完整的文件。
前端不要自动无限重试
结果过大通常不会因重复同一请求而消失。界面应保留筛选条件,给出缩小范围或改用异步导出的入口。网络波动与确定性的容量错误要分开处理;后者不宜继续用激进重试制造额外负载。
给接口设定可执行的预算
页大小由服务端约束
客户端传入的页大小需要校验并限制范围,不能让调用方通过一个参数恢复无界读取。页面支持的排序、筛选与导出字段也应使用明确名单,避免不同组合意外放大结果。前端若做无限滚动,还应限制本地保留的数据量,否则后端分页成功,浏览器仍可能因为累积过多记录而变慢。
为异常保留定位线索
当某个查询触发容量错误,记录请求关联标识、接口版本和筛选范围类别,方便还原条件;敏感筛选值应按现有隐私规则处理。对历史下载任务保留进度与失败原因,让运维能区分读取失败、文件生成失败和下载授权过期。这样下一次排查才不会只看到一条模糊的“导出失败”。
上线验收围绕最大真实场景
在测试环境准备宽字段、多字节文本、空结果、分页边界和重复时间值。再模拟读取期间新增、删除或修改记录,检查业务能够接受的一致性语义。错误路径也要测试,确认不会展示成空列表,更不能把导出失败标记为完成。
上线后同时追踪异常率、响应大小分布、查询耗时与导出完成率。若分页改动出问题,回退应保留字段和范围限制,不能重新放开无界查询。此次变更的实际价值,是促使全栈团队把“取多少、怎样继续、何时算完成”写进接口契约,而不是临时把一个数字调小。
评论
暂无评论。