laravel 10+ 必须安装 maatwebsite/excel:^4.0，否则会因版本不兼容导致 excel::import() 静默失败、类未找到或 “undefined array key 'type'” 错误；需移除旧 facade、使用 laravel 原生 excel 门面、启用配置并关闭 cache.enabled。
用 maatwebsite/excel 导入 Excel 数据，Laravel 10+ 必须装 maatwebsite/excel:^4.0，装错版本（比如 ^3.1）会导致 Excel::import() 静默失败、Class "Maatwebsite\Excel\ExcelServiceProvider" not found 或 Undefined array key "type" —— 这不是你代码写错了，是包根本没对上。
装哪个版本？怎么装才不翻车
新版 Laravel（10/11）和 PHP 8.1+ 只认 maatwebsite/excel:^4.0。别信“先装再调包”这种老教程，v3 和 v4 的命名空间、Facade、配置结构全变了。
- 运行
composer require maatwebsite/excel:^4.0（必须带^4.0，否则可能装到不兼容的 4.x 小版本） - 删掉
config/app.php里的'Excel' => Maatwebsite\Excel\Facades\Excel::class—— v4 已弃用这个 Facade - 所有调用统一用
use Illuminate\Support\Facades\Excel;（Laravel 自带门面） - 运行
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config生成新配置，尤其要检查config/excel.php里'cache' => ['enabled' => true]是否开着——关掉它能避开Undefined array key "type"
Import 类里怎么读对第一行（表头）
默认 $row 是数字索引（$row[0], $row[1]），但多数人想要按列名（$row['name']）取值。这就得靠 WithHeadingRow，但它只在第一行是纯表头时才可靠。
- 如果 Excel 第 1 行确实是字段名（如 “姓名,邮箱,手机号”），在 Import 类里
implements ToModel, WithHeadingRow即可 - 如果第 1 行有合并单元格或空行，改用
headingRow() { return 0; }，然后手动定义protected $heading = ['name', 'email', 'phone'];，并在model(array $row)前加$row = array_combine($this->heading, $row); - 中文列名乱码？不是编码问题，是 PhpSpreadsheet 默认转小写+去空格。统一加
$row = array_change_key_case($row, CASE_LOWER);再处理
控制器里传文件路径，不是 UploadedFile 对象
Excel::import(new UsersImport, $request->file('import')) 是典型错误写法 —— import() 第二个参数必须是字符串路径或 SplFileInfo 实例，UploadedFile 不符合。
- 正确做法：
$path = $request->file('import')->store('imports');→ 得到类似imports/xxx.xlsx的相对路径 - 拼成完整路径：
storage_path('app/' . $path)（漏掉storage_path('app/')会报File not found） - 导入完成后可选删临时文件：
Storage::delete($path) - 加文件类型限制：前端
<input type="file" accept=".xlsx,.csv">，后端用$request->file('import')->getClientOriginalExtension()校验
大数据量导入卡死？Chunk + Queue 是必选项
10,000 行以上不加处理，PHP 很容易内存溢出或超时，错误通常是 Allowed memory size exhausted 或 max_execution_time 超限。
- Import 类加
implements WithChunkReading, ShouldQueue - 实现
chunkSize(): int { return 500; }（每批读 500 行） - 控制器里用
Excel::import(new UsersImport, $fullPath)->onQueue('imports'); - 别在
model()里调User::create()，保持返回模型实例，框架会自动批量插入；若需事务控制，改用WithTransaction
最常被忽略的一点：config/excel.php 里的 cache.enabled 默认为 true，但在 Laravel 10+ 下它和 phpoffice/phpspreadsheet 的键名约定冲突，直接导致 Undefined array key "type"。关掉它比调各种缓存驱动更省事。
