Laravel Eloquent cursor 怎样处理大结果集

Eloquent 的 cursor() 适合逐条处理查询结果：主查询只执行一次，模型在迭代时才逐个实例化。它能减少同时存在的模型数量，但不能保证整个进程内存恒定，PDO 原始结果缓冲和业务代码保留的对象仍可能占用大量内存。

官方文档：https://laravel.com/docs/12.x/eloquent

以下按 Laravel 12.x 官方接口说明，示例假定项目已配置数据库，并有包含 id、status、total_cents 字段的 Invoice 模型。代码用于说明读取方式，未声称完成压测或数据库执行。

先理解 cursor 省下的是哪一层内存

比较 cursor 与 get 时，先区分模型层与驱动层。get 会取得完整模型集合；cursor 返回 LazyCollection，按需构建模型。因此，“逐条模型”描述的是 Eloquent 对象的消费方式，不能直接解释为数据库服务端游标或完全无缓冲连接。

Laravel 官方文档专门提醒，PDO 内部原始结果缓冲会使极大结果集仍面临内存问题，此时可考虑 lazy。PHP 的 MySQL 文档也区分缓冲与非缓冲查询；不同驱动、配置和记录宽度会影响实际占用，不能给 cursor 承诺一个通用内存上限。

不要为了套用“流式”这个词就直接关闭连接缓冲。MySQL 非缓冲查询还会影响同一连接上其他查询的可用时机。若项目有模型事件、访问器或关系访问，实际调用可能比外层 foreach 更复杂。

逐条消费时不要重新堆积模型

select(['id', 'total_cents'])
    ->where('status', 'settled')
    ->orderBy('id')
    ->cursor();

foreach ($rows as $invoice) {
    // 逐条计算标量，不把模型放回一个不断增长的数组
    $totalCents += (int) $invoice->total_cents;
    $processed++;
}

// 此处使用计数与汇总值；金额范围需符合项目整数容量约定

示例只保留两个标量。若循环中执行 $all[] = $invoice，就重新延长了所有模型的生命周期。对 LazyCollection 调用会收集全部元素的终结操作，同样可能抵消惰性消费带来的收益。

能在 SQL 中表达的筛选条件，优先放在查询构造器中；不要先读出大量无关记录，再依赖 PHP 过滤。对纯计数或求和，数据库聚合可能比逐条实例化模型更合适。这里保留 cursor 是为了展示确实需要每条模型参与处理时的写法。

核对代码时可查看三点：是否只取必要字段，是否在循环中保存模型，是否有隐藏的关系访问。此处的检查是读者实施建议，不代表示例已产生某个实测内存数字。

按关系加载和更新需求选择替代方案

cursor 不支持关系预加载。若每条记录都要访问关联对象，不应假设加上 with 就能保留预加载语义；可以改用支持该需求的 lazy，并保留关联所需主键、外键。否则逐条触发关系查询，可能把内存问题变成大量查询问题。

lazyById(500) as $invoice) {
    // 这里只演示修改筛选列；真正外部导出应另行设计幂等和失败处理
    $invoice->exported = true;
    $invoice->save();
}

这个对比示例使用 lazyById，因为循环会修改用于筛选的 exported 列。不要修改推进所依赖的主键，也不要把分块迭代自动当作一致性快照或“恰好执行一次”的保证。批大小 500 是示例参数，需要结合记录大小和处理开销选择。

把长任务的失败范围控制清楚

长时间任务建议放在队列或命令中，并明确超时、重试与进度记录。若每条处理涉及外部副作用，应让处理动作具有幂等标识；仅记住最后打印过的 ID，不能代替事务与外部系统之间的协调设计。

排查时分别记录查询耗时、处理条数、最后完成项及进程内存趋势。若内存随条数上涨，先查看业务保留引用和集合收集操作，再考虑驱动缓冲与读取方式。若内存稳定但任务很慢，则查看查询计划、每条处理和额外关系查询。

最终选择不应只看 API 名称：逐条消费但规模可控时，cursor 很直观；有关系预加载或极大原始结果时，优先评估 lazy；修改筛选字段时再考虑 lazyById。它们解决的约束不同，不存在对所有任务都最优的一个方法。

cursor 会每行查询一次吗？

主查询不是每行重新执行。循环内部主动查询或访问关系，仍可能额外发出 SQL。

使用 cursor 后还要限制字段吗？

需要。较宽字段仍影响传输、驱动缓冲和当前模型的占用。

cursor 是分页接口吗？

不是用户页面的游标分页。这里讨论批处理模型迭代，不提供页面导航游标。

驱动缓冲参考：https://www.php.net/manual/en/mysqlinfo.concepts.buffering.php

惰性集合参考：https://laravel.com/docs/12.x/collections