“Laravel 从零到一用 cursor() + 生成器 实现百万用户 CSV 导出”
这不仅是 Laravel 的高级技巧，更是 内存算法、流式处理、性能优化 的综合体现。

---

一、知识体系：百万用户 CSV 导出的完整知识体系（六大模块）

要真正掌握这一功能，必须构建以下完整知识体系：

---

1. 核心目标与挑战

目标	说明
导出百万用户数据	数据量大，不能全加载到内存
避免内存溢出（OOM）	传统 User::all() 会崩溃
恒定内存占用	无论数据多少，内存不增长
流式下载	用户无需等待，边生成边下载
支持大文件	文件大小可能达 GB 级

✅ 核心是 “内存算法” + “流式处理”

---

2. 关键技术：cursor() 与生成器

技术	说明
cursor()	不查询所有数据，而是返回一个游标（Generator），逐行读取
生成器（Generator）	使用 yield 延迟返回数据，内存恒定
response()->stream()	流式响应，分块输出，避免内存堆积

✅ 三者结合实现 O(1) 内存复杂度

---

3. CSV 导出流程设计

[用户请求导出]
   ↓
[Laravel 控制器]
   ↓
User::cursor() → 逐行读取数据库
   ↓
生成器格式化为 CSV 行
   ↓
response()->stream() 分块输出
   ↓
浏览器接收并下载

✅ 数据“流过”系统，不驻留内存

---

4. 性能与内存优化策略

优化点	说明
只查必要字段	select('id', 'name', 'email')
禁用 Eloquent 模型	用 ->useWritePdo()->select(...) 避免模型实例化
设置输出缓冲	ob_flush() + flush() 立即输出
分批处理	虽然 cursor() 已流式，但可结合 chunk() 控制事务
数据库索引	确保查询高效

✅ 每一步都为“内存友好”服务

---

5. 安全与用户体验

安全问题	解决方案
未授权访问	中间件验证权限
大文件超时	设置 set_time_limit(0)
浏览器兼容	设置正确的 Content-Type 和 Content-Disposition
进度反馈	前端显示“导出中”状态

✅ 安全与体验同样重要

---

6. Swoole / Hyperf 中的优化

场景	优化
Swoole 常驻内存	避免 static 变量累积
协程支持	在协程中使用 cursor()，不阻塞其他请求
连接池	复用数据库连接
异步导出	入队列，完成后发邮件通知下载链接

✅ 在高性能框架中，可进一步优化

---

二、底层原理：cursor() + 生成器如何实现流式导出？

我们深入 Laravel 和 PHP 内核，解析其底层机制。

---

1. cursor() 的底层实现

User::cursor();

源码流程（Illuminate/Database/Eloquent/Builder.php）：

public function cursor()
{
    if ($this->useWritePdo) {
        return $this->connection->cursor(
            $this->toSql(), 
            $this->getBindings(), 
            $this->useWritePdo
        );
    }

    return $this->onceWithColumns(['*'], function () {
        return $this->processor->processSelect($this, $this->runSelect());
    })->cursor();
}

关键点：

• 使用数据库 游标（Cursor）
• 不获取所有结果，而是逐行 fetch()
• 返回一个 Generator

✅ 内存只保存当前行，不随数据量增长

---

2. 生成器（Generator）的协程机制

function exportUsers() {
    foreach (User::cursor() as $user) {
        yield [$user->id, $user->name, $user->email];
    }
}

底层：

• yield 不是 return，函数不会结束
• 局部变量（如 $user）保留在协程栈中
• 下次 foreach 时恢复执行
• 内存只保存当前状态

✅ 生成器是“轻量级协程”，内存恒定

---

3. 流式响应（stream）的实现

return response()->stream(function () {
    $handle = fopen('php://output', 'w');
    fputcsv($handle, ['ID', 'Name', 'Email']);

    foreach (User::cursor() as $user) {
        fputcsv($handle, [$user->id, $user->name, $user->email]);
    }

    fclose($handle);
}, 200, [
    'Content-Type' => 'text/csv',
    'Content-Disposition' => 'attachment; filename="users.csv"',
]);

底层机制：

• php://output 是 PHP 的输出流
• fputcsv() 直接写入 HTTP 响应体
• flush() 强制立即输出到客户端
• 分块传输（Chunked Transfer Encoding）

✅ 数据“流过”系统，不构建大字符串

---

4. 内存占用对比

方式	内存复杂度	百万用户内存占用
User::all()	O(n)	几百 MB 甚至 GB，OOM
cursor() + 生成器	O(1)	恒定 ~几 MB

✅ cursor() 是处理大数据的唯一可行方案

---

5. 数据库游标的底层机制

数据库	游标实现
MySQL	SELECT ... 返回结果集，PHP 逐行 mysql_fetch_row()
PostgreSQL	支持服务器端游标（DECLARE cursor）
SQLite	本地游标，逐行读取

✅ 游标是数据库的“流式查询”机制

---

三、从零到一：完整实现代码

1. 路由

// routes/web.php
Route::get('/export/users', [ExportController::class, 'exportUsers']);

2. 控制器

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Response;

class ExportController extends Controller
{
    public function exportUsers()
    {
        // 设置不限时
        set_time_limit(0);

        return Response::stream(function () {
            // 打开输出流
            $handle = fopen('php://output', 'w');

            // 输出 BOM（防止 Excel 乱码）
            fprintf($handle, chr(0xEF).chr(0xBB).chr(0xBF));

            // 写入表头
            fputcsv($handle, ['ID', 'Name', 'Email', 'Created At']);

            // 流式读取用户
            User::select('id', 'name', 'email', 'created_at')
                ->cursor()
                ->each(function ($user) use ($handle) {
                    fputcsv($handle, [
                        $user->id,
                        $user->name,
                        $user->email,
                        $user->created_at,
                    ]);
                });

            // 关闭输出流
            fclose($handle);
        }, 200, [
            'Content-Type' => 'text/csv; charset=UTF-8',
            'Content-Disposition' => 'attachment; filename="users_'.now()->format('Y-m-d').'.csv"',
            'Cache-Control' => 'no-cache, no-store, must-revalidate',
        ]);
    }
}

3. 可选：中间件（权限控制）

// app/Http/Middleware/CanExport.php
public function handle($request, Closure $next)
{
    if (! $request->user()->can('export-users')) {
        abort(403);
    }
    return $next($request);
}

---

四、总结

✅ 知识体系（六大模块）

模块	核心内容
1. 核心目标	百万数据、避免 OOM
2. 关键技术	cursor()、生成器、stream
3. 流程设计	流式导出，边读边写
4. 性能优化	只查必要字段、禁用模型
5. 安全与体验	权限、超时、文件名
6. Swoole 优化	协程、连接池、异步

---

✅ 底层原理（四大核心）

原理	说明
cursor() 使用数据库游标	逐行拉取，O(1) 内存
生成器协程机制	yield 暂停，状态保留
stream() 分块输出	避免大字符串 OOM
fputcsv() 直接写流	不构建大数组

---

✅ 最终结论：

使用 cursor() + 生成器 + stream() 实现百万用户 CSV 导出，是 Laravel 高级开发的标志性技能。
它体现了：

• 内存算法思维：O(1) 内存复杂度
• 流式处理思想：数据“流过”系统
• 性能优化能力：处理大数据不崩溃

掌握这一技术，你将能：

• 处理任意规模的数据导出
• 构建企业级后台系统
• 在 Swoole 中实现高性能流式服务

🚀 推荐：在 Hyperf 中实现异步 CSV 导出，任务入队，完成后邮件通知下载链接，体验完整的企业级方案。