流式导出是唯一靠谱方案，因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，都可能导致导出一半失败，且错误日志里还找不到痕迹。
