流式导出是唯一靠谱方案，因Storage::put()等会全量写入内存或磁盘导致内存溢出、超时和中断；必须用response()->stream()配合chunkById()、fputcsv()和BOM写入实现边查边写。

直接用 response()->stream() 是唯一靠谱的方案，否则内存爆掉、超时、导出中断全是大概率事件。

为什么不能用 Storage::put() 或 file_put_contents() 生成 CSV 后再下载

因为整个文件会先写入内存或磁盘临时文件，数据量一过 10 万行，PHP 内存很容易突破 memory_limit（哪怕设到 512M 也扛不住百万级）；而且用户得等全部写完才开始下载，体验差、易超时。

流式输出的核心是边查边写边响应，不缓存整张表：

• 数据库查询用 chunkById() 或游标分页（避免 OFFSET 深度翻页性能崩塌）
• 每批数据立即写入 php://output，不落地
• 响应头必须提前设置好 Content-Type 和 Content-Disposition

如何用 response()->stream() 实现真正流式 CSV 导出

关键不是“怎么生成 CSV”，而是“怎么把生成过程挂进响应流”。Laravel 的 stream() 接收一个回调函数，每次响应刷出前调用它一次——你就在这个回调里做「连接数据库 → 分批取数据 → 格式化为 CSV 行 → fputcsv() 写入 stdout」的事。

注意三点：

• 回调函数内不能用 Eloquent 的 get() 或 all()，必须用 chunkById(500, ...) 控制单次内存占用
• fputcsv() 第二个参数必须是数组，字段顺序要和 header 严格一致
• 务必在回调开头用 ob_end_clean() 清掉可能存在的输出缓冲，否则 CSV 里混入空格或 HTML 就打不开

public function exportCsv()
{
    $headers = [
        'Content-Type' => 'text/csv',
        'Content-Disposition' => 'attachment; filename="users.csv"',
    ];

    $callback = function () {
        $handle = fopen('php://output', 'w');
        fputcsv($handle, ['ID', 'Name', 'Email', 'Created At']);

        User::orderBy('id')->chunkById(500, function ($users) use ($handle) {
            foreach ($users as $user) {
                fputcsv($handle, [
                    $user->id,
                    str_replace(["\n", "\r"], ' ', $user->name),
                    $user->email,
                    $user->created_at->format('Y-m-d H:i:s'),
                ]);
            }
        });

        fclose($handle);
    };

    return response()->stream($callback, 200, $headers);
}

遇到 Maximum execution time of X seconds exceeded 怎么办

不是加 set_time_limit(0) 就完事。流式导出本质是长连接，Web 服务器（Nginx/Apache）和 PHP-FPM 都有各自超时限制，漏掉任何一个都会断连。

必须同步调整三处：

• PHP：set_time_limit(0) 放在 stream 回调最开头（不是控制器方法里）
• PHP-FPM：request_terminate_timeout 设为 0 或足够大（如 3600）
• Nginx：proxy_read_timeout 和 fastcgi_read_timeout 都要设成 > 导出预估耗时

另外，chunkById() 的 size 别盲目调大——500~1000 是较稳的平衡点；太大单次查询慢，太小网络 I/O 次数多，反而拖慢整体速度。

中文乱码、Excel 打开显示一堆问号怎么办

不是编码没设 UTF-8，而是 Excel 默认不认 UTF-8 BOM。Windows 上的 Excel 要靠 BOM 识别编码，否则一律当 ANSI 解析。

解决办法只有一条：在 CSV 内容最开头手动写入 UTF-8 BOM 字节（\xEF\xBB\xBF）。

但注意：BOM 必须在第一次 fputcsv() 之前写入，且只能写一次，不能写进每行数据里：

$handle = fopen('php://output', 'w');
fwrite($handle, "\xEF\xBB\xBF"); // ← 这一行最关键
fputcsv($handle, ['ID', '姓名', '邮箱']); // 中文 header 正常了

如果用的是 Laravel 10+，response()->stream() 默认禁用输出缓冲，但某些 Swoole 或 RoadRunner 环境仍可能拦截 BOM，这时得确认底层是否吞掉了开头字节——最保险的方式是改用 response()->streamDownload()（Laravel 10.29+）并显式传入 BOM 前缀。

流式导出真正的难点不在代码几行，而在于对「请求生命周期」「输出缓冲链路」「Web 服务器超时机制」这三者的交叉理解。少调一个 ob_end_clean()，少配一个 proxy_read_timeout，都可能导致导出一半失败，且错误日志里还找不到痕迹。