先说几个关键要点：使用PhpSpreadsheet批量导入Excel，核心思路是先验证文件格式与大小，再采用流式读取避免内存溢出，随后清洗数据并完成字段映射，最后分批事务插入确保稳定与高效。这套流程跑通后，成百上千条数据就能一次性写入数据库，无需逐条手动添加——当然，前提是必须避开内存溢出、超时中断、字段错位、类型报错等常见陷阱。
安装并验证 phpspreadsheet 组件
直接执行 composer require phpoffice/phpspreadsheet 即可，它会自动拉取最新版本。不过需要注意，TP6 项目必须确保 PHP 版本在 7.4 以上，否则类加载会静默失败，连错误提示都不显示，排查起来非常棘手。
在控制器顶部写入完整命名空间：use PhpOffice\PhpSpreadsheet\IOFactory;。这个【PhpOffice】前缀绝不能遗漏，运行时若出现 “Class not found” 错误，十有八九就是这里出了问題。
还有一点：不要手动下载 ZIP 放到 vendor 目录下。TP6 已弃用自动注册机制，只认 Composer 的 PSR-4 自动加载路径，手动放置等于白费力气。
安全接收并校验上传文件
如何确保文件安全可靠？有两种思路。
第一种是用 request()->file('file') 获取上传对象，然后调用 ->validate(['ext' => 'xlsx,xls', 'size' => 10485760]) 限制格式和大小，10MB 以内。
但说实话，我更推荐第二种方法——手动校验。用 finfo_file() 读取真实的 MIME 类型，直接拒绝 text/csv 或 application/octet-stream 这类伪装文件。这里必须强调一下：【$_FILES['file']['type'] 完全不可信，跳过这个字段】，它太容易被篡改了。
提取后缀时用 $ext = strtolower(pathinfo($filePath, PATHINFO_EXTENSION));，只允许 xlsx 或 xls，其他格式一律中断并返回错误。这一步虽然简单，但能有效防范不少低级攻击。
流式读取 Excel 避免内存爆炸
内存问题是批量导入的常见杀手，这里分几步来搞定。
第一步，根据扩展名创建对应的 Reader。如果是 xlsx，就用 $reader = IOFactory::createReader('Xlsx');；如果是 xls，就用 $reader = IOFactory::createReader('Xls');。
第二步，关闭非数据解析：$reader->setReadDataOnly(true);。这个操作能跳过公式、样式、合并单元格等干扰项，内存占用直接下降 60% 以上，效果立竿见影。
第三步，加载文件并获取首张工作表：$spreadsheet = $reader->load($filePath); $worksheet = $spreadsheet->getActiveSheet();。
第四步，启用行迭代器，每次只读 500 行：foreach ($worksheet->getRowIterator(2, 502) as $row) { ... }。起始行设为 2 是为了跳过表头，结束行动态计算，读完后立刻 unset($row) 释放内存，避免积压。
第五步，遍历单元格时强制读取所有列：$cellIterator->setIterateOnlyExistingCells(false);。这一步很关键，否则空列会被跳过，导致后续列数据整体左移，造成字段错位。
清洗数据并映射到数据库字段
Excel 的第一行必须是中文或英文表头，比如 ["用户姓名", "手机号", "注册时间"]。然后硬编码映射规则：$map = ['用户姓名' => 'username', '手机号' => 'mobile', '注册时间' => 'create_time'];。
遇到“是/否”、“启用/禁用”这类文本值，需要转成数据库能接受的整型：$val = in_array($cellVal, ['是', '启用', 'true'], true) ? 1 : 0;。
日期列是个常见陷阱。不能依赖 Excel 的自动识别，$cell->getFormattedValue() 返回的可能是带格式的字符串，必须用 PhpOffice\PhpSpreadsheet\Shared\Date::excelToTimestamp($raw) 转成 Unix 时间戳，再格式化为 'Y-m-d H:i:s'。这一步不能偷懒，否则日期数据会混乱。
分批插入并控制事务边界
将清洗后的数据按 300 条切片：$chunks = array_chunk($cleanData, 300);。为什么是 300 条？MySQL 默认的 max_allowed_packet=4M，单批超过 400 行就容易触发 SQL 错误，300 条是一个比较稳妥的阈值。
每批开启独立事务：Db::startTrans(); try { Db::name('user')->insertAll($chunk); Db::commit(); } catch (Exception $e) { Db::rollback(); throw $e; }。这样即使某批数据出问题，也不会影响其他批次。
这里要特别提醒一下：不要用 sa veAll()。它默认会触发验证器和事件钩子，但我们的数据已经清洗过，完全可信，用 insertAll() 更快更直接。另外，【字段名必须与数据库列名完全一致，否则静默丢弃】，连报错都不会有，排查起来很费时间。
