使用 PhpSpreadsheet 实现 Excel 批量导入：先验证文件格式与大小，再流式读取避免内存溢出，清洗数据并映射字段，最后分批事务插入确保稳定高效。
你需要把 Excel 表格里的几百上千条用户信息一次性写进数据库，而不是一条条手动添加——这要求你避开内存爆掉、超时中断、字段错位、类型报错这些常见坑，直接跑通稳定可复用的导入流程。
安装并验证 phpspreadsheet 组件
执行 composer require phpoffice/phpspreadsheet 安装最新版；TP6 项目必须确保 PHP ≥ 7.4，否则类加载会静默失败。
在控制器顶部写全命名空间：use PhpOffice\PhpSpreadsheet\IOFactory; ——漏掉 【PhpOffice\】 前缀，运行时必报 “Class not found”。
别手动下载 ZIP 放 vendor 目录，TP6 已弃用自动注册机制，只认 Composer 的 PSR-4 自动加载路径。
立即学习“PHP免费学习笔记（深入）”；
安全接收并校验上传文件
方法一：用 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：
① 若 $ext === 'xlsx' → $reader = IOFactory::createReader('Xlsx');
② 若 $ext === '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); ——MySQL 默认 max_allowed_packet=4M，单批超 400 行易触发 SQL 错误。
每批开启独立事务：Db::startTrans(); try { Db::name('user')->insertAll($chunk); Db::commit(); } catch (\Exception $e) { Db::rollback(); throw $e; }
别用 saveAll()：它默认触发验证器和事件钩子，而清洗后的数据已可信，insertAll() 更快且不填充 create_time 等自动字段，【字段名必须与数据库列名完全一致，否则静默丢弃】。
