必须用队列+Redis实现实时进度更新，避免同步导出阻塞；分块查询与写入防内存溢出；确保job_id全链路一致且Redis key设过期时间；文件存storage/app/exports并正确配置软链。
导出时页面卡死，前端收不到进度更新？用队列 + Redis 实时存进度
根本原因是 Laravel 默认的同步导出阻塞了整个请求生命周期，浏览器拿不到中间状态。必须把导出任务扔进队列，同时用 Redis（或数据库）在任务执行过程中持续写入进度值。
实操建议：
- 用
php artisan queue:work启动队列监听器（别用sync驱动） - 在导出任务类的
handle()里，每处理完 100 条数据就调用一次Redis::set("export_progress:$jobId", $percent) - 前端轮询接口（如
/api/export/progress?job_id=xxx），该接口直接读Redis::get("export_progress:$jobId") - 注意：不要在任务里用
sleep()模拟耗时，真实场景中应基于实际数据分块处理逻辑来更新进度
导出大文件时内存爆掉（Allowed memory size exhausted）？别一次性查全量数据
常见错误是用 Model::get() 把几万条记录全载入内存，再逐条写入 CSV 或 Excel，PHP 进程瞬间吃光内存。
实操建议：
- 改用
Model::chunk(500, function ($items) { ... })分批拉取，每次只保留当前批次对象 - 写文件时用原生
fputcsv()或PhpSpreadsheet的fromArray()+setAutoSize(false)关闭自动列宽计算 - 避免在循环里新建模型实例或调用
toArray()；优先用pluck()或select('id', 'name')->get()只取必要字段 - 如果用
maatwebsite/excel，务必设置WithChunkReading和ShouldQueue接口，并在chunkSize()方法里返回合理数值（如 200）
前端轮询返回空或旧进度？Redis key 过期或 job_id 不一致
典型现象是前端一直收到 null 或固定值（比如始终是 0），实际后台任务已在跑。大概率是前后端使用的 job_id 对不上，或 Redis key 被提前清理。
实操建议：
- 生成 job_id 时别用
Str::uuid()后又丢给前端一部分——确保前后端传的是同一个完整字符串，推荐用uniqid('', true)或数据库自增 ID 做关联标识 - Redis key 必须设过期时间：
Redis::setex("export_progress:$jobId", 3600, $percent)，防止堆积 - 队列任务失败时，记得在
failed()方法里写入Redis::setex("export_progress:$jobId", 3600, -1)表示出错，前端可据此提示“导出失败” - 别依赖 session 或 cookie 存 job_id，它们可能跨请求丢失；必须通过 API 响应体明确返回 job_id 字段
导出完成后文件链接无效或 404？临时文件没持久化或路径权限不对
很多人把文件写到 storage/app/temp/ 下，但没配好 php artisan storage:link，或者用 response()->download() 时路径拼错了。
实操建议：
- 文件统一存到
storage/app/exports/目录下，用Storage::disk('local')->put("exports/{$filename}", $content) - 提供下载地址时走
route('export.download', ['filename' => $filename])，控制器里用return Storage::disk('local')->download("exports/{$filename}") - 检查
config/filesystems.php中local磁盘的root是否指向正确的storage_path('app') - 如果部署在 Nginx，确认
location ~ ^/storage/(.*)$有正确 alias 指向storage/app，否则用户无法直链访问
事情说清了就结束。最常漏掉的是 Redis key 生命周期管理和 job_id 全链路一致性——这两个点一错，进度反馈就彻底失联。
