PHP 导出大数据内存耗尽排查：从一次性数组到流式写 CSV

后台导出 CSV 是 PHP 项目里很常见的功能。小数据量时，先查出数组、再拼成字符串、最后一次性返回，代码看起来很直接。但数据从几千行变成几十万行后，页面可能突然变成 500，日志里只剩一句内存不足。

本文从一个“订单导出偶发失败”的现场出发，按问题排查顺序走一遍：先确认是不是 PHP 内存耗尽，再定位一次性数组和字符串拼接，最后改成分页读取、生成器产出行、fputcsv 流式写入。目标是让导出链路可持续跑完，而不是单纯把 memory_limit 调大。

问题现场：小数据能导出，大数据直接 500

假设后台有一个订单导出接口，本地测试导出 2000 行没有问题，线上运营选择一个月范围后就失败。PHP 错误日志里可能出现类似信息：

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted
while exporting /admin/orders/export

常见旧写法大概是这样：

findByDateRange($start, $end);

$rows = [];
$rows[] = ['订单号', '用户ID', '金额', '状态', '创建时间'];

foreach ($orders as $order) {
    $rows[] = [
        $order['order_no'],
        $order['user_id'],
        $order['amount'],
        $order['status'],
        $order['created_at'],
    ];
}

$content = '';
foreach ($rows as $row) {
    $content .= implode(',', $row) . \"\\n\";
}

header('Content-Type: text/csv; charset=UTF-8');
header('Content-Disposition: attachment; filename=\"orders.csv\"');
echo $content;

这段代码的问题不是某一行语法错，而是数据在内存里被保存了多份：数据库结果一份，$rows 一份，最终 $content 字符串一份。数据量上来后，峰值内存很容易超过限制。

初步判断：先确认内存在哪里涨

第一步不要急着调大 memory_limit。先在导出入口加临时日志，记录关键阶段的内存峰值。这样能判断问题发生在查询、转换，还是拼接输出阶段。

findByDateRange($start, $end);
logMemory('after query');

$rows = buildRows($orders);
logMemory('after rows');

$content = buildCsvContent($rows);
logMemory('after csv');

如果 after query 已经很高，说明一次性查询结果太大；如果 after rows 和 after csv 继续大幅增长，说明中间转换和字符串拼接又复制了数据。

动手验证：复现一次性数组的内存曲线

可以写一个最小脚本模拟 20 万行导出，先不连数据库，直接构造数组。这样能把问题从业务系统里剥离出来。

 'NO' . str_pad((string) $i, 8, '0', STR_PAD_LEFT),
            'user_id' => $i % 10000,
            'amount' => number_format(($i % 5000) / 10, 2, '.', ''),
            'status' => 'paid',
            'created_at' => '2026-06-29 10:00:00',
        ];
    }
    return $orders;
}

$orders = makeOrders(200000);
echo memory_get_peak_usage(true) / 1024 / 1024, \"MB\\n\";

这个脚本的意义是提醒我们：大导出不是普通列表页。列表页只返回当前页，导出可能要处理全部匹配数据。把全部数据一次性放进数组，天然会把内存推高。

定位原因：查询、映射、拼接都在堆内存里叠加

导出接口的内存峰值通常来自三层叠加：

• 查询层：一次性拿回所有订单，数据库结果数组常驻内存。
• 转换层：把订单再映射成 CSV 行数组，形成第二份数据。
• 输出层：把所有行拼成一个大字符串，形成第三份数据。

如果每一层都“先攒起来再处理”，内存只会越来越高。修复方向很明确：让数据一批一批查，一行一行写，写完就释放，不在 PHP 里保存完整导出文件。

修复方案：分页读取并流式写 CSV

修复后的核心结构是：浏览器请求进入 PHP，PHP 设置下载响应头，打开 php://output，先写表头，再分页读取订单，每拿到一行就用 fputcsv 写出去。

findAfterId($start, $end, $lastId, $pageSize);
        if (!$orders) {
            break;
        }

        foreach ($orders as $order) {
            $lastId = (int) $order['id'];
            yield [
                $order['order_no'],
                $order['user_id'],
                $order['amount'],
                $order['status'],
                $order['created_at'],
            ];
        }
    }
}

function downloadOrdersCsv(OrderRepository $repo, string $start, string $end): void
{
    header('Content-Type: text/csv; charset=UTF-8');
    header('Content-Disposition: attachment; filename=\"orders.csv\"');
    header('X-Accel-Buffering: no');

    $out = fopen('php://output', 'w');
    fputcsv($out, ['订单号', '用户ID', '金额', '状态', '创建时间']);

    foreach (orderRows($repo, $start, $end) as $row) {
        fputcsv($out, $row);
    }

    fclose($out);
}

这里有几个关键点：

• 分页不要用深分页 OFFSET 一直跳，优先用递增主键或稳定游标。
• 生成器每次只产出一行，调用方写完就继续下一行。
• fputcsv 负责处理逗号、引号和换行，比手写 implode 稳定。
• 如果前面还有 Nginx 缓冲，按实际环境决定是否关闭缓冲或改走异步导出。

验证结果：看峰值内存、行数和响应头

改完以后要做三类复查。

第一，看峰值内存是否稳定

保留前面的 memory_get_peak_usage() 临时日志，导出 1 万、10 万、50 万行，对比峰值是否随行数线性暴涨。流式写入后，峰值通常主要受单页查询大小影响。

第二，核对导出行数

导出完成后，用命令核对行数。包含表头时，总行数应该是数据行数加一。

wc -l orders.csv

第三，检查响应头和文件格式

浏览器应当触发下载，响应头里有 Content-Type 和 Content-Disposition。打开 CSV 时，字段包含逗号、引号或换行也应该保持列结构正常。

总结清单：导出接口上线前检查什么

1. 不要一次性查询全部数据，按主键游标或稳定条件分页读取。
2. 不要把所有 CSV 行攒进数组，使用生成器逐行产出。
3. 不要手写字符串拼接 CSV，优先使用 fputcsv。
4. 导出前记录筛选条件，限制最大时间范围或最大行数。
5. 用峰值内存、导出行数、响应头和文件预览做复查。
6. 超大导出建议改成后台任务，生成文件后再通知用户下载。

总结一下，PHP CSV 导出内存耗尽的根因，通常不是某个配置太小，而是导出链路把数据重复攒在内存里。先用日志确认峰值位置，再把一次性查询、数组映射和字符串拼接改成分页读取、生成器产出和 fputcsv 流式写入，导出接口就会更稳，也更容易观测和限制。