Excel导入需分块读取、控制事务、防止类型错误：用getRowIterator()分块读、setReadDataOnly(true)减内存、每块≤500行并及时释放变量；insertAll()单次≤1000条；严格清洗字段、校验并记录前20条错误。
大 Excel 导入不加控制，1 万行就容易内存溢出、超时、锁表或丢精度——核心不是“能不能导入”，而是“怎么分块读、怎么控事务、怎么防类型错”。
用 getRowIterator() 分块读 Excel，别碰 toArray()
直接 load() + toArray() 是最常见内存爆掉的根源。它会把整张表（含空行、样式、公式）全塞进 PHP 内存，哪怕只有 5000 行 × 20 列也常超 256M 限制。
-
setReadDataOnly(true)必开：跳过字体、颜色、合并单元格等无关解析，提速 3–5 倍，减内存 60%+ - 用
getRowIterator(2, 500)从第 2 行开始，每次只取 500 行（标题在第 1 行），避免单次加载过多 - 每轮迭代完立刻
unset($row)和$cell = null，防止 PhpSpreadsheet 内部引用滞留 - 绝对不要在循环里调
$worksheet->getCellByColumnAndRow($col, $rowIndex)->getValue()多次——改用getCoordinate()+ 缓存列映射，减少对象创建
事务中调 insertAll()，单次 ≤ 1000 条
insertAll() 不是越大越好。MySQL 默认 max_allowed_packet=4M，1000 条含 varchar(255) 的记录基本逼近上限；再大就报 Packets larger than max_allowed_packet are not allowed。
- 每块解析出的 500 行数据，组装成二维数组后，包进
Db::transaction()执行insertAll() - 事务内禁止调外部 API、发邮件、写日志文件——只做 DB 操作，否则锁持有时间拉长，阻塞其他请求
- 捕获
Throwable后必须重新 throw，否则 ThinkPHP 不会自动回滚（try/catch吞掉异常就等于放弃事务） - 若需更高吞吐，可改用原生 SQL 拼接
INSERT INTO ... VALUES (),(),()，但要自己处理字段转义和长度截断
Excel 字段清洗必须做三件事：标题清理、数字防科学计数、日期转 DateTime
用户上传的 Excel 里，标题带空格、换行、全角字符太常见；数值列被 Excel 自动转成 1.23456789E+10，直接 intval() 就丢精度；日期显示为 44205 这种序列值，不是字符串。
立即学习“PHP免费学习笔记（深入）”；
- 标题行用
trim(str_replace(["\n","\r","\t"," "], "", $header))清洗，再小写化或映射白名单（如['用户名','user_name','name'] → 'name'） - 数值列先判断
$cell->getDataType() === \PhpOffice\PhpSpreadsheet\Cell\Cell::TYPE_NUMERIC，再用$cell->getFormattedValue()获取原始显示值，避免科学计数 - 日期列别用
strtotime()解析字符串，直接传$cell->getValue()给\PhpOffice\PhpSpreadsheet\Shared\Date::excelToDateTimeObject() - 空单元格统一转
null（对应数据库 NULL），别留''或0，否则 int 字段插入失败报Data truncated for column
错误必须带行号记录，且只返回前 20 条给前端
导入失败不能只抛异常或返回“导入失败”，用户需要知道哪几行、为什么错。但也不能把全部 5000 行错误都吐给前端——页面卡死、日志爆炸、暴露敏感逻辑。
- 每行校验失败时，收集
['row' => $rowIndex, 'column' => $colName, 'error' => '手机号格式错误']到数组 - 全局错误数超 20 条就中断当前块处理（不继续浪费资源），但继续读下一块——保证至少能入库部分有效数据
- 最终返回 JSON 结构里包含
"errors": [...]（≤20 条）和"success_count"，后端同时写完整日志到runtime/log/import_20260419.log - 注意：行号是 Excel 显示行号（从 1 开始），不是数组下标；
getRowIterator()的$rowIndex是真实行号，别用foreach($rows as $i => $row)的$i
