直接用 maatwebsite/excel 包是最稳妥的选择，但新版 Laravel（10+）和 PHP 8.1+ 下容易因配置或依赖冲突导致 Import 类不触发、toArray() 返回空、甚至 PhpSpreadsheet 报 Undefined array key "type" 错误——问题不在 Excel 文件本身，而在包版本与 Laravel 的兼容逻辑。
确认安装的是兼容版本的 maatwebsite/excel
别盲目 composer require maatwebsite/excel。Laravel 10.x 必须用 ^3.1，且需对应 phpoffice/phpspreadsheet ^1.26。运行以下命令强制对齐：
composer require maatwebsite/excel:^3.1.49 phpoffice/phpspreadsheet:^1.26.0
如果已装错版本，先 composer remove maatwebsite/excel 清干净再重装。否则 php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" 可能不生成配置，后续 Excel::import() 会静默失败。
写一个最小可运行的 Import 类，别急着加验证和事务
先确保数据能进来，再考虑健壮性。新建 app/Imports/UsersImport.php，内容保持极简：
$row[0] ?? null,
'email' => $row[1] ?? null,
]);
}
}
关键点：
-
$row默认是数字索引数组（从第 1 行开始读），不是关联键名；想用列名得额外实现WithHeading -
?? null防止空单元格触发ArrayAccess错误 - 别在
model()里调User::create()，交给框架批量处理更安全
控制器里调用要传真实文件路径，别传 Request 对象本身
Excel::import(new UsersImport, $request->file('import')) 是常见错误写法——$request->file() 返回的是 UploadedFile 实例，而 import() 第二个参数必须是路径字符串或 SplFileInfo。正确做法：
- 先
$path = $request->file('import')->store('imports') - 再
Excel::import(new UsersImport, storage_path('app/' . $path)) - 导入完可选删临时文件：
Storage::delete($path)
漏掉 storage_path('app/...') 这层路径拼接，会报 File not found，因为 store() 存的是相对路径。
遇到 Undefined array key "type" 就检查 config/excel.php 的 cache 配置
这个错实际来自 phpspreadsheet 内部读取缓存驱动时的键名变更。Laravel 10 默认用 array 缓存，但 maatwebsite/excel 某些小版本会硬编码读 "type" 键。解决方法：
- 执行
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config - 打开
config/excel.php，找到'cache' => [...]块，把'driver' => 'array'改成'driver' => 'none' - 或者干脆删掉整个
'cache'配置项（包会 fallback 到默认安全值）
改完记得 php artisan config:clear，否则缓存仍生效。
真正卡住人的往往不是语法，而是版本胶水层里的隐式依赖和路径语义差异。多打一行 dd($request->file('import')) 或 dd(storage_path('app/' . $path))，比查十篇“教程”更快定位问题。
