用 maatwebsite/excel 导出 Excel 前必须确认的三件事
别急着写 Excel::download()，先检查这三项，否则 90% 的导出失败都卡在这儿：
• Laravel 版本是否与 maatwebsite/excel 兼容（比如 Laravel 10 需用 ^3.1，不是 ^2.1）
• 是否已执行 php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" 并生成配置
• config/excel.php 中的 'cache' => 'redis' 若启用了 Redis，但服务未运行，导出会直接报 Connection refused
Excel::download() 返回空文件或 500 错误的典型原因
常见现象：浏览器下载了一个 0 字节的 .xlsx，或者页面报 Class 'PhpOffice\PhpSpreadsheet\Writer\Xlsx' not found
• 这通常是因为没装底层依赖：运行 composer require phpoffice/phpspreadsheet（注意不是 phpexcel，那个已废弃）
• 如果用的是 PHP 8.2+，maatwebsite/excel ^3.1 默认依赖的 phpspreadsheet ^1.28 有兼容问题，降级到 ^1.27 更稳
• 导出大表时内存溢出，错误信息是 Allowed memory size exhausted：改用 FromQuery 或 WithChunkReading，别一次性 get() 全部数据
导出带样式/多 Sheet 的最小可行写法
不推荐从头写样式类，直接复用官方提供的接口更可靠：
• 设置列宽和居中：在导出类里加 public function styles(Worksheet $sheet) 方法，返回数组如 ['A1:Z1' => ['font' => ['bold' => true], 'alignment' => ['horizontal' => 'center']]
• 多 Sheet：用 WithMultipleSheets 接口，sheets() 方法返回多个导出类实例，每个类控制一个 Sheet
• 注意：WithHeadings 和 WithMapping 不能同时用于同一个导出类，否则 map() 返回的数组键名会覆盖表头
导出 CSV 时中文乱码、Excel 打开提示“文件格式不匹配”
这不是编码问题，是 BOM 头缺失导致的：
• 不要用 return response()->stream() 手动输出 CSV
• 正确做法：继承 Maatwebsite\Excel\Concerns\Exportable，并在导出类中实现 ShouldAutoSize + WithEvents，然后在 registerEvents() 里加 BeforeWriting 事件，手动写入 UTF-8 BOM（\xEF\xBB\xBF）
• 更简单方案：改用 Maatwebsite\Excel\Concerns\WithCustomCsvSettings，设置 useBom() === true
• 如果导出后 Excel 提示“文件格式与扩展名不匹配”，说明你用了 .csv 后缀但实际输出了 xlsx 内容——检查 registerEvents() 里有没有误调 Writer::XLSX
