laravel 10.x + php 8.1+ 下必须使用 maatwebsite/excel:^3.1.49 和 phpoffice/phpspreadsheet:^1.26.0，否则 excel::import() 会静默失败或报 "undefined array key 'type'" 错误；需强制卸载重装、发布配置、校验 cache 驱动并规范路径与索引访问。
maatwebsite/excel 在 PHP 8.1+ 和 Laravel 10.x+ 下必须用 ^3.1.49，否则 Excel::import() 会静默失败或报 Undefined array key "type" ——这不是你 Excel 文件的问题，是包版本错配导致的底层缓存键名解析异常。
确认安装的是 Laravel 10 + PHP 8.1 兼容组合
运行以下命令强制对齐依赖，别信 composer require maatwebsite/excel 默认装的版本：
composer remove maatwebsite/excel<br>composer require maatwebsite/excel:^3.1.49 phpoffice/phpspreadsheet:^1.26.0
装完立刻执行：
php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider"
如果这步没输出“Published”，说明配置没生成，后续所有导入都会无声失效。
-
config/excel.php必须存在，且其中'cache' => ['driver' => 'memory']是安全默认值；若改用redis或file，需确保对应驱动已启用，否则触发"type"错误 - 不要跳过
composer dump-autoload，尤其在手动移动或重命名app/Imports/类后 - Laravel 10 默认禁用
Excel门面，如需使用，得在config/app.php的'aliases'中显式加一行：'Excel' => Maatwebsite\Excel\Facades\Excel::class
Import 类里别直接 new Model() 或调 create()
用 ToModel 接口时，model(array $row) 返回的是待插入实例，框架内部会批量处理。写成 User::create(...) 或 DB::insert(...) 会导致事务失控、事件丢失、性能暴跌。
-
$row默认是数字索引（$row[0],$row[1]），不是关联数组；想按列名取值，必须同时实现WithHeadingRow - 空单元格会触发
ArrayAccess报错，所有字段访问都得带空合并：$row['email'] ?? null，不能裸写$row['email'] - 密码哈希等逻辑应放在模型的
setPasswordAttribute()里，而非model()中硬编码bcrypt()
控制器里传路径，不是 UploadedFile 对象
Excel::import(new UsersImport, $request->file('import')) 是高频错误——import() 第二个参数只接受字符串路径或 SplFileInfo，不接受 UploadedFile 实例。
- 正确流程：
$path = $request->file('import')->store('imports')→ 得到类似imports/xyz.xlsx的相对路径 - 拼完整物理路径：
storage_path('app/' . $path)，漏掉storage_path('app/')这层，就报File not found - 导入成功后建议清理：
Storage::delete($path)，否则临时文件堆积 - 如需异步导入百万级数据，加
ShouldQueue接口并确保队列已配置，别在同步请求里扛大文件
大数据量时别死磕 Excel::import()
单次读取 10 万行 Excel，内存很容易破 512MB。Laravel Excel 的 WithChunkReading 只缓解，不根治。
- 真正百万级导入，优先转 CSV，走 MySQL
LOAD DATA INFILE：快 10 倍、内存恒定、无 PHP 解析开销 - 若必须 Excel，用
FromCollection+DB::table()->upsert()手动分块，绕过 Eloquent 生命周期 - 禁用模型事件可提速 20%：
Event::fake([UserCreated::class])放在model()外围 - 验证别放
WithValidation，它会在每行都跑一次 validator 实例；改用数组级检查 +skipOnFailure()收集错误行
config/excel.php 里的缓存驱动、store() 返回的相对路径、$row 索引类型、以及百万行时是否该切 MySQL 原生命令——这些点不显眼，但任一出错，导入就卡在「没报错也没入库」的状态。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
