用maatwebsite/excel因CSV不支持样式、多sheet、公式等，而该包基于phpspreadsheet可真实还原Excel行为，但内存高、大文件需分块+队列处理。
为什么用 maatwebsite/excel 而不是直接读写 CSV？
因为 Excel（.xlsx）有样式、多 sheet、公式、合并单元格等，CSV 压根不支持。直接用 fgetcsv 或 str_getcsv 会漏掉这些，还容易在中文、日期、数字格式上出错。而 maatwebsite/excel 底层用的是 phpspreadsheet，能真实还原 Excel 行为——但代价是内存占用高、大文件易超时。
实操建议：
- 导入超过 10,000 行时，必须用
WithChunkReading+queue，否则 PHP 内存溢出或超时 - 导出大量数据别用
Excel::download()直接返回，改用Excel::store()先存到storage/app，再发下载链接 - Laravel 10+ 已默认禁用
public_path()写入，导出路径必须用storage_path('app/exports')这类受控路径
Import 类里怎么处理空值和类型自动转换？
Excel 单元格看着是空，实际可能是空字符串、NULL、空白符，甚至 Excel 的「空单元格」在 PHP 里读成 0 或 ''。默认行为不会帮你转类型——比如「2024-03-15」读出来是 float（Excel 内部存为序列号），不手动处理就会变成 45366。
实操建议：
- 在
toArray()方法里用trim()和is_null()清洗空值，别依赖empty() - 日期列用
PhpOffice\PhpSpreadsheet\Shared\Date::excelToDateTimeObject($value)转，别用date('Y-m-d', $value) - 数字列加
filter_var($value, FILTER_VALIDATE_FLOAT)防止文本型数字混入（如「123.00」被当字符串）
导出时报 Class 'Maatwebsite\Excel\Excel' not found 怎么办？
这是 Laravel 9+ 的典型兼容问题：maatwebsite/excel 3.x 不支持 Laravel 9+ 的自动服务发现，且命名空间变了。装了包却找不到类，大概率是没注册 Provider 或用了旧版 Facade。
实操建议：
- 确认装的是
phpoffice/phpspreadsheet+maatwebsite/excel:^4.0（Laravel 9/10/11 必须用 v4） - 删掉
config/app.php里的'Excel' => Maatwebsite\Excel\Facades\Excel::class，v4 已弃用该 Facade - 所有调用改用
use Illuminate\Support\Facades\Excel;（Laravel 自带门面）或直接注入ExcelExporter实例 - 运行
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config生成新配置
为什么导出的 Excel 打开提示「发现不可读内容」？
常见于导出时写了非法字符（如 \u0000）、BOM 头、或响应头没设对。特别是从数据库取的字段含控制字符（比如 MySQL 的 TEXT 字段存了 \r\n\t 混合），直接塞进 Excel 单元格就会破坏 XML 结构。
实操建议：
- 导出前对每行数据做
preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/', '', $str)清除不可见控制符 - 确保
response()->streamDownload()或Excel::download()返回的是标准响应，不要在中间件或控制器里提前echo或dd() - 如果用 Nginx，检查是否开了
gzip on，Excel 是二进制流，gzip 可能损坏它；临时关掉试试
真正麻烦的不是语法，是 Excel 文件本身不声不响地容忍错误，但换个环境（比如 WPS 或 Mac Numbers）就直接打不开。处理前先用 phpspreadsheet 自带的 IOFactory::load() 读一遍原始数据，能早暴露格式问题。
