laravel 10/11 必须使用 maatwebsite/excel:^4.0（依赖 phpoffice/phpspreadsheet:^2.0），旧版会报 class not found；需重装指定版本、改用 illuminate\support\facades\excel、加 withchunkreading/withskippedemptyrows/withencoding 等处理大文件、乱码、空行；表头统一转小写、手动映射字段、日期用 exceltodatetimeobject 转换；验证失败用 withvalidation + skiponfailure 或捕获 validationexception 获取具体错误行。
用 maatwebsite/excel:^4.0 导入 Excel，在 Laravel 10+ 上跑不通，基本是版本或配置没对齐——不是代码写错了，是底层依赖断了。
装错版本直接报 Class not found
Laravel 10/11 必须用 maatwebsite/excel:^4.0，它强制依赖 phpoffice/phpspreadsheet:^2.0。装 ^3.1 或不带版本号的 composer require maatwebsite/excel，大概率触发：
Class "Maatwebsite\Excel\ExcelServiceProvider" not foundCall to undefined method Illuminate\Foundation\Application::bindShared()
实操建议：
- 删掉旧包：
composer remove maatwebsite/excel - 重装指定版本：
composer require maatwebsite/excel:^4.0 - v4 已弃用
Excel门面，所有调用改用Illuminate\Support\Facades\Excel或注入实例 - 禁用了自动发现？才需手动加
Maatwebsite\Excel\ExcelServiceProvider::class到config/app.php
导入大文件内存爆、中文乱码、空行报错
toModel() 默认把整张表读进内存，10 万行 Excel 很容易 Allowed memory size exhausted；Windows 下生成的 Excel 含中文，常因编码识别失败变成 ????；空行也会触发 model() 创建空模型。
实操建议：
- 加
WithChunkReading接口，实现chunkSize()返回500–1000 - 导入前链式调用
->withEncoding('UTF-8')（仅 v4 支持） - 实现
WithSkippedEmptyRows，跳过全空行 - 表单加
accept=".xlsx,.csv"，避免上传 .xls 格式引发PhpSpreadsheet\Exception
表头映射失败：列名变小写、含空格、合并单元格崩
PhpSpreadsheet 默认把表头转成小写、去空格、去特殊符号，$row['User Name'] 会变成 $row['username']；首行有合并单元格时，WithHeadingRow 直接读错列索引。
实操建议：
- 统一键名处理：
$row = array_change_key_case($row, CASE_LOWER);放在model()开头 - 合并表头？改用
headingRow()返回0，再手动定义字段映射数组 - 列名含空格或点号？别依赖
WithHeadingRow，改用toArray()+ 索引访问，比如$row[0]、$row[1] - 日期列必须用
PhpOffice\PhpSpreadsheet\Shared\Date::excelToDateTimeObject($value)转，不能直接date('Y-m-d', $value)
验证失败后想跳过错误行，但整个导入中断了
默认行为是任意一行验证失败就抛异常，import() 中断，用户看不到哪几行出错。
实操建议：
- 导入类实现
WithValidation，定义rules()和customValidationAttributes() - 控制器里用
try/catch捕获Maatwebsite\Excel\Validators\ValidationException - 调用
$exception->failures()获取具体失败行和错误信息，返回给前端 - 不想中断？加
skipOnFailure()或skipOnError()（v4 支持），但注意这会让脏数据进库
真正难的不是写 model()，是让导入在各种脏文件、乱编码、空合并单元格、超长日期格式下还能稳住——这些边界情况不提前压测，上线后第一份用户上传的 Excel 就会卡住整个流程。
