Laravel 中 cursor 方法的内存优化策略与 PDO 参数调优

Respect yourself

398人浏览 · 2026-03-13 00:24:24

Respect yourself · 2026-03-13 00:24:24 发布

1. 从一次深夜告警说起：我的80万数据查询“爆”了内存

那天晚上，我正在家里追剧，手机突然开始疯狂震动。拿起来一看，监控告警：线上一个数据迁移脚本因为内存溢出（OOM）被系统强制杀掉了。脚本的逻辑很简单，就是把一张有80万条记录的stored_events表数据全部捞出来，逐条做一些清洗和归档处理。我当时心想，这脚本我用了Laravel的cursor()方法啊，理论上应该是“游标”模式，一次只加载一行数据到内存，怎么会把16G的机器内存给吃光呢？

我赶紧连上服务器，查看了脚本的日志。为了监控内存，我在循环里加了memory_get_usage()的打印。日志显示，脚本启动时内存占用不到1G，但随着处理的记录数增加，内存占用像爬坡一样稳步上升。处理到第40万条时，内存已经涨到了接近12G，最终在60万条左右触发了OOM。这完全违背了我对cursor()的认知——它不应该是个内存友好的“懒加载”神器吗？

这个坑让我熬了一个通宵。但解决问题的过程，也让我彻底搞明白了Laravel cursor方法背后，PDO（PHP数据对象）那个关键参数PDO::ATTR_EMULATE_PREPARES的“魔法”。今天，我就把这个从踩坑到填坑的全过程，以及背后的原理和优化策略，掰开揉碎了分享给你。无论你是正在处理大数据报表，还是构建数据同步管道，理解这个细节都能帮你避免很多“内存悄悄增长”的灵异事件。

2. 重新认识Laravel的cursor：它真的省内存吗？

在Laravel的Eloquent ORM中，当我们面对大量数据时，通常会被告知：不要用get()，要用cursor()。这个建议本身没错，但很多人（包括之前的我）对它存在一个美丽的误会——认为cursor()是绝对的内存“白嫖”者。

让我们先看看get()和cursor()最直观的区别：

// 方式一：使用get() - 内存杀手
$events = EloquentStoredEvent::query()->get(); // 一瞬间，80万条数据全部变成Eloquent对象数组，装入内存
foreach ($events as $event) {
    // 处理逻辑
}

// 方式二：使用cursor() - 期望中的内存救星
$events = EloquentStoredEvent::query()->cursor(); // 这里返回的是一个Generator（生成器）
foreach ($events as $event) {
    // 处理逻辑
}

当你调用get()时，Laravel会执行SQL查询，然后PDO驱动会将整个结果集从MySQL服务器拉取到PHP进程的内存中，接着Laravel会遍历这个结果集，为每一行数据实例化一个Eloquent模型对象，最终你得到一个包含所有模型的Collection。如果你的表有80万行，每行数据就算只有1KB，光原始数据就接近800MB，再加上PHP对象的内存开销（一个空对象就有几百字节），内存占用轻松突破几个G。

而cursor()的聪明之处在于，它利用了PHP的生成器（Generator）。它执行查询后，并不立即获取所有结果，而是返回一个生成器对象。当你开始foreach循环时，它才通过PDO的fetch()方法，一次从MySQL服务器端的结果集中取出一行数据，转换成Eloquent对象，yield给你处理。处理完这一行，生成器内部会进行下一轮fetch。从理想模型上看，同一时刻内存里应该只有“一行数据+一个Eloquent对象”。

但是，问题就出在这个“理想模型”和“现实实现”的差距上。 我最初就是被这个理想模型给“骗”了。我的测试代码和最初遇到问题的代码类似：

public function handle() {
    EloquentStoredEvent::query()->cursor()->each(function (EloquentStoredEvent $storedEvent) {
        // 一些处理逻辑...
        $this->info(round(memory_get_usage()/1024/1024, 2).'MB');
    });
}

跑起来之后，终端输出的内存数字让我傻眼了：962.36MB, 1023.45MB, 1105.12MB... 数字在持续增长！这根本不是“常量内存”，而是一个随着处理行数线性增长的“变量内存”。这意味着，如果数据量足够大，或者脚本运行时间足够长，OOM是迟早的事。那么，本该省内存的cursor，为什么内存会增长呢？秘密就藏在PHP与MySQL通信的底层——PDO的配置里。

3. 揪出内存增长的“元凶”：PDO::ATTR_EMULATE_PREPARES

为了定位问题，我不得不抛开Laravel，写一个最纯粹的PDO测试脚本来复现和观察。这个过程就像侦探破案，需要一层层剥离框架的封装，直击核心。

我构建了下面这个最小化的复现Demo：

<?php
ini_set('memory_limit', '3024M'); // 临时调高内存限制以便观察

class SimpleDb {
    public $dbh;
    
    public function __construct($emulatePrepares) {
        $this->dbh = new PDO('mysql:host=127.0.0.1;port=3306;dbname=your_database', 'username', 'password', [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_STRINGIFY_FETCHES => false, // 重要：防止数字被转为字符串
            PDO::ATTR_EMULATE_PREPARES => $emulatePrepares, // 核心参数！
        ]);
    }
    
    public function fetchAllAtOnce() {
        $stmt = $this->dbh->query("SELECT * FROM stored_events");
        return $stmt->fetchAll(PDO::FETCH_OBJ); // 一次性全取
    }
    
    public function fetchWithCursor() {
        $stmt = $this->dbh->prepare("SELECT * FROM stored_events");
        $stmt->execute();
        while ($record = $stmt->fetch(PDO::FETCH_OBJ)) {
            yield $record; // 模拟cursor，一行行取
        }
    }
}

// 测试场景1：EMULATE_PREPARES = false (Laravel默认值)
echo "测试 PDO::ATTR_EMULATE_PREPARES = false\n";
$dbFalse = new SimpleDb(false);
echo '开始前内存: ' . round(memory_get_usage()/1024/1024, 2) . "MB\n";

$generator = $dbFalse->fetchWithCursor();
$count = 0;
foreach ($generator as $row) {
    $count++;
    if ($count % 10000 == 0) { // 每1万行打印一次
        echo "已处理 {$count} 行，当前内存: " . round(memory_get_usage()/1024/1024, 2) . "MB\n";
    }
    // 模拟处理逻辑
    $dummy = $row->id;
}
echo "处理完成，最终内存: " . round(memory_get_usage()/1024/1024, 2) . "MB\n\n";

// 测试场景2：EMULATE_PREPARES = true
echo "测试 PDO::ATTR_EMULATE_PREPARES = true\n";
$dbTrue = new SimpleDb(true);
echo '开始前内存: ' . round(memory_get_usage()/1024/1024, 2) . "MB\n";

$generator = $dbTrue->fetchWithCursor();
$count = 0;
foreach ($generator as $row) {
    $count++;
    if ($count % 10000 == 0) {
        echo "已处理 {$count} 行，当前内存: " . round(memory_get_usage()/1024/1024, 2) . "MB\n";
    }
    $dummy = $row->id;
}
echo "处理完成，最终内存: " . round(memory_get_usage()/1024/1024, 2) . "MB\n";

运行这个脚本，你会看到截然不同的两种内存表现：

当 PDO::ATTR_EMULATE_PREPARES = false 时，内存使用量会随着循环处理行数的增加而持续增长。
当 PDO::ATTR_EMULATE_PREPARES = true 时，内存使用量会在循环开始后迅速上升到一个较高的固定值，然后在整个循环过程中保持稳定，不再增长。

这个参数到底是什么？为什么有如此神奇的效果？

PDO::ATTR_EMULATE_PREPARES 控制的是PDO对“预处理语句”（Prepared Statements）的模拟行为。

true（模拟模式）：PDO会在客户端（即你的PHP进程）模拟预处理语句。它先把完整的SQL语句发送给MySQL执行，MySQL返回一个结果集。然后PDO驱动在PHP内存中缓存整个结果集。当你调用fetch()时，它只是从这个本地缓存里移动指针，取出下一行数据。所以内存占用在execute()之后就是固定的（整个结果集的大小），后续fetch不会增加内存。
false（原生模式）：PDO使用MySQL服务器端的原生预处理语句。prepare()只是把SQL模板发给MySQL，execute()执行后，结果集保存在MySQL服务器端。每次PHP调用fetch()，才会通过网络从MySQL服务器取回一行数据。听起来很省内存对吧？但这里有个关键：为了维持这个“服务器端游标”，PDO（具体是pdo_mysql驱动）需要在客户端维护一些缓冲区和管理状态。在某些版本和配置下，每fetch一行，这些内部缓冲区的管理开销可能会累积，导致PHP进程的内存使用量缓慢增长，而不是我们期望的“常量”。

这就解释了开头的现象：Laravel默认使用PDO::ATTR_EMULATE_PREPARES = false，所以当你用cursor()遍历大量数据时，虽然数据是一行行取的，但PDO内部的管理开销在累积，导致了内存的“隐形增长”。

4. 深入拆解：PDO参数调优与组合拳策略

知道了“元凶”是PDO::ATTR_EMULATE_PREPARES，是不是简单把它改成true就万事大吉了？事情没这么简单。这个参数是一把双刃剑，我们需要权衡利弊，并结合其他参数打出“组合拳”。

首先，我们来看看这两个模式的详细对比：

特性对比	`PDO::ATTR_EMULATE_PREPARES = true` (模拟模式)	`PDO::ATTR_EMULATE_PREPARES = false` (原生模式)
内存行为	内存占用高但稳定。一次性加载全部结果集到PHP内存。	内存占用起点低，但可能随fetch次数缓慢增长。
网络IO	一次性大量数据传输，后续无网络交互。	多次小数据包传输（一行一行fetch）。
安全性	参数绑定在客户端完成，存在SQL注入风险隐患（如果手动拼接）。	使用MySQL服务端预处理，理论上更安全。
性能	对于中小型结果集，减少网络往返，可能更快。	对于超大型结果集，避免一次性内存压力，更可靠。
适用场景	结果集大小可控（比如小于100MB），且查询频繁。	处理海量数据导出、批量迁移，内存是首要考虑。

那么，在Laravel中我们该如何设置呢？ 你不能直接在模型查询里设置，需要在数据库连接配置层面修改。打开config/database.php，找到你的数据库连接配置（例如mysql）：

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    // ... 其他配置
    'options' => extension_loaded('pdo_mysql') ? array_filter([
        PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
        // 关键配置在这里：
        PDO::ATTR_EMULATE_PREPARES => env('DB_EMULATE_PREPARES', false), // 可以通过.env控制
    ]) : [],
],

我建议通过环境变量.env文件来控制，方便不同环境配置不同策略：

# 对于处理大数据任务的后台队列Worker，可以设为true
DB_EMULATE_PREPARES=true

# 对于普通的Web请求，保持默认的false以保障安全
# DB_EMULATE_PREPARES=false

但是，仅仅切换这一个参数还不够优化。这里给你分享我实战中的“PDO调优组合拳”：

PDO::MYSQL_ATTR_USE_BUFFERED_QUERY (默认为true) 这个参数控制是否使用缓冲查询。当它为true时（默认），行为类似于EMULATE_PREPARES=true，会在客户端缓存结果集。当它为false时，才是真正的“无缓冲查询”，结果集留在服务器端，用游标一行行取。在EMULATE_PREPARES=false时，将其设为false，可以进一步减少客户端的内存管理开销，抑制内存增长。 但注意，在同一个连接上，你不能在未遍历完一个无缓冲查询的结果集时，执行新的查询。
```
'options' => [
    PDO::ATTR_EMULATE_PREPARES => false,
    PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false, // 启用无缓冲查询
]
```
PDO::ATTR_STRINGIFY_FETCHES (建议设为false) 这个参数如果为true，PDO在fetch时会把所有字段（包括整数、浮点数）都转换成字符串。这会增加内存分配和复制开销。对于数值型主键ID、金额等字段，保持为false可以节省内存并提升一点性能。
PDO::ATTR_DEFAULT_FETCH_MODE 设置默认的获取模式。对于cursor()，Laravel内部会使用PDO::FETCH_OBJ或PDO::FETCH_CLASS来构建Eloquent对象。保持默认即可，但如果你自己写PDO，知道这个参数可以避免额外的模式设置调用。

一个我常用的、针对大数据cursor场景的优化配置如下：

'options' => [
    PDO::ATTR_EMULATE_PREPARES => true, // 为了内存稳定，牺牲一点安全性（需确保无注入风险）
    PDO::ATTR_STRINGIFY_FETCHES => false,
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    // 如果EMULATE_PREPARES设为false，则考虑加上下面这行
    // PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false,
],

重要警告： 将EMULATE_PREPARES设为true会禁用服务器端预处理，如果您的应用程序依赖预处理语句来防止SQL注入（例如，使用未经验证的用户输入进行查询），您必须格外小心，确保所有用户输入都经过适当的转义或验证。在Laravel中，只要坚持使用Eloquent或查询构建器的参数绑定（where('column', $value)），安全风险是可控的，因为Laravel会在发送给PDO前完成参数绑定。

5. 超越PDO：Laravel层面的高级内存优化技巧

调整PDO参数是治标，要想从根本上优雅地处理海量数据，我们还需要在Laravel应用层动动脑筋。下面是我在多个项目中总结出的几种进阶策略。

5.1 分块查询（chunk） vs 游标（cursor）：如何选择？

很多人会混淆chunk()和cursor()。它们都用于处理大量数据，但原理和适用场景不同。

chunk()：它通过limit和offset进行分页查询。每次从数据库取出一“块”数据（比如1000条），处理完这一块后，再查询下一块。
```
EloquentStoredEvent::query()->chunk(1000, function ($events) {
    foreach ($events as $event) {
        // 处理
    }
});
```
优点：内存控制明确，每块处理完内存会被释放（理论上）。缺点：offset在数据量非常大时性能很差（越往后越慢），且如果处理过程中数据有增删，可能导致重复处理或遗漏。
cursor()：基于数据库游标，顺序流式读取。优点：性能稳定，不受数据偏移影响，能感知数据实时状态。缺点：受制于PDO底层行为，可能内存缓慢增长（如前所述），且在整个cursor遍历完成前，需要保持数据库连接和事务状态。

我的选择建议是：

如果数据量在百万级以下，且需要强一致性（处理过程中数据不能变），用cursor()并配合优化PDO参数。
如果数据量极大（千万以上），或者允许数据有轻微变动，用chunk()，并最好搭配基于主键或唯一索引的where条件进行分块，而不是用offset。这就是下面要说的“游标分块”。

5.2 游标分块（Cursor-based Chunking）：兼顾性能与内存的终极方案

这是我最推荐用于超大数据处理的模式。它结合了cursor的顺序读取优势和chunk的内存可控性。

核心思想：利用自增主键或有序唯一键，进行“锚点查询”。

$lastId = 0;
$chunkSize = 5000;

do {
    $events = EloquentStoredEvent::query()
        ->where('id', '>', $lastId)
        ->orderBy('id')
        ->limit($chunkSize)
        ->get(); // 这里用get，因为每块数据量可控

    if ($events->isEmpty()) {
        break;
    }

    foreach ($events as $event) {
        // 处理你的业务逻辑
        processEvent($event);
    }

    // 更新最后一个ID
    $lastId = $events->last()->id;

    // 可选：显式释放内存（对于大块数据有用）
    unset($events);
    
    // 输出进度
    $this->info("Processed up to ID: {$lastId}");
    
} while (true);

这个方案的优点：

内存稳定：每次只加载最多$chunkSize条数据到内存，处理完即释放。
性能极佳：where('id', '>', $lastId)和orderBy('id')可以利用索引进行高效的范围查询，性能远胜于offset。
数据一致：基于ID的锚点查询，不受处理期间新增数据的影响（新增数据的ID更大，会在后续轮次中被处理），也不会重复或遗漏。

5.3 放弃Eloquent，拥抱原生查询与简单对象

Eloquent模型非常强大，但创建每一个Eloquent对象都有不小的开销（属性访问器、事件监听器、关系加载器等）。当处理百万级数据时，这个开销累积起来非常恐怖。

优化策略：在纯数据处理的场景下，降级使用。

// 方案A：使用查询构建器，获取StdClass对象
DB::table('stored_events')->orderBy('id')->cursor()->each(function ($record) {
    // $record 是一个 stdClass 对象，比Eloquent轻量得多
    $id = $record->id;
    $payload = json_decode($record->payload, true);
    // ... 处理逻辑
});

// 方案B：使用PDO直接获取数组（最轻量）
$pdo = DB::connection()->getPdo();
$stmt = $pdo->prepare('SELECT id, payload FROM stored_events ORDER BY id');
$stmt->execute();

while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) { // 获取关联数组
    $id = $row['id'];
    $payload = json_decode($row['payload'], true);
    // ... 处理逻辑
    // 及时释放对当前行的引用
    unset($row);
}

从Eloquent对象 -> StdClass对象 -> 纯PHP数组，内存消耗是逐级显著下降的。在我的一个数据清洗任务中，将Eloquent换成PDO::FETCH_ASSOC，内存峰值直接下降了60%。

5.4 利用生成器与yield，构建自定义数据管道

Laravel的cursor()本身返回的就是一个生成器。我们可以借鉴这个思想，在复杂的多步数据处理中，构建一个完整的生成器管道，确保数据像流水一样通过，而不在中间环节堆积。

假设我们需要：1. 从A表读数据；2. 调用一个API转换；3. 写入B表。

function readFromTableA() {
    $query = DB::table('table_a')->where('status', 'pending')->orderBy('id');
    foreach ($query->cursor() as $item) {
        yield $item; // 逐行产出
    }
}

function transformData($generator) {
    foreach ($generator as $item) {
        // 模拟一个转换，比如调用内部服务
        $transformed = someTransformFunction($item);
        yield $transformed; // 转换后继续产出
    }
}

function writeToTableB($generator) {
    foreach ($generator as $data) {
        DB::table('table_b')->insert($data);
        yield $data; // 可以继续产出，或者只写入不产出
    }
}

// 组装管道
$pipeline = writeToTableB(transformData(readFromTableA()));

// 启动管道，数据开始流动
foreach ($pipeline as $_) {
    // 这里可以添加进度记录，但内存中始终只有少量数据
    if ($processedCount++ % 1000 == 0) {
        echo "Processed $processedCount records.\n";
    }
}

这种模式将内存占用降至最低，因为每个环节都只处理当前的一个数据项。

6. 实战：一个完整的数据迁移脚本优化案例

光说不练假把式。最后，我分享一个真实的案例，看看如何将上述所有策略应用到一个具体脚本中。

需求：将users表中created_at在一年前的所有用户数据（约500万条），归档到users_archive表，并在归档后清理原表部分字段。

第一版（问题版）：

// 内存爆炸版
User::where('created_at', '<', now()->subYear())
    ->cursor()
    ->each(function ($user) {
        UserArchive::create($user->toArray()); // 使用Eloquent创建，开销大
        $user->update(['profile_data' => null]); // 触发Eloquent事件
    });

问题：使用了Eloquent cursor但未调整PDO，内存缓慢增长。同时，在循环内进行create和update操作，产生大量数据库短连接和事务开销，速度极慢。

最终优化版：

// 高性能稳定版
public function handle() {
    // 1. 为本次执行临时修改PDO配置（避免影响其他业务）
    config(['database.connections.mysql.options.' . PDO::ATTR_EMULATE_PREPARES => true]);
    DB::purge('mysql'); // 清除连接池，使新配置生效

    $lastId = 0;
    $chunkSize = 2000;
    $processed = 0;

    do {
        // 2. 使用游标分块，获取轻量级StdClass对象
        $users = DB::table('users')->select('id', 'name', 'email', 'created_at', 'profile_data')
                    ->where('created_at', '<', now()->subYear())
                    ->where('id', '>', $lastId)
                    ->orderBy('id')
                    ->limit($chunkSize)
                    ->get();

        if ($users->isEmpty()) {
            break;
        }

        // 3. 准备批量插入数据
        $archiveData = [];
        $updateIds = [];

        foreach ($users as $user) {
            $archiveData[] = [
                'original_id' => $user->id,
                'name' => $user->name,
                'email' => $user->email,
                'archived_at' => now(),
            ];
            $updateIds[] = $user->id;
        }

        // 4. 使用事务+批量操作，极大提升效率
        DB::transaction(function () use ($archiveData, $updateIds) {
            // 批量插入归档表
            if (!empty($archiveData)) {
                DB::table('users_archive')->insert($archiveData);
            }
            // 批量更新原表
            DB::table('users')->whereIn('id', $updateIds)
                ->update(['profile_data' => null, 'archived_at' => now()]);
        });

        $lastId = $users->last()->id;
        $processed += $users->count();

        // 5. 每处理完一批，输出日志并强制垃圾回收（针对超大数据量）
        $this->info(sprintf('Archived %d users, up to ID: %d, Memory: %.2fMB', 
                      $processed, $lastId, memory_get_peak_usage(true) / 1024 / 1024));

        unset($users, $archiveData, $updateIds);
        gc_collect_cycles(); // 建议在明确知道产生大量循环引用时使用

    } while (true);

    $this->info('Data archiving completed successfully.');
}

这个优化版带来的提升：