Box/Spout是PHP 8.1下高效导入Excel的唯一推荐方案，流式读取使10万行仅耗3秒、内存稳定3–8MB；需禁用PHPExcel/PhpSpreadsheet，因其加载全结构导致内存溢出与超时。
PHP 8.1 下导入 Excel 数据，别碰 PHPExcel，它在 8.1+ 会直接报 Fatal error: Uncaught Error: Call to undefined method；也别无脑用 PhpSpreadsheet::toArray()，10 万行文件可能吃掉 500MB 内存并卡死。真正快且稳的路径只有一条：用 box/spout 流式读取 + 手动映射 + 批量插入。
为什么不能用 PhpSpreadsheet 做大数据导入
PhpSpreadsheet 功能全、兼容好，但设计目标不是吞吐量——它默认加载样式、字体、公式、合并单元格元数据，哪怕你只要数值。即使开了 $reader->setReadDataOnly(true)，getRowIterator() 仍需将整张表结构载入内存，对 10 万行以上文件，GC 压力大、耗时翻倍。
- 常见错误现象：
Allowed memory size exhausted（即使设了 512M）、max_execution_time超时、日期列变成44562这类序列号 - 性能影响：解析一个 8MB
.xlsx，平均耗时 12–18 秒，内存峰值常超 300MB - 兼容性没问题，但它不是“快”的解法——8.1 支持，但不推荐用于导入主流程
box/spout 是什么，怎么装
box/spout 是纯 PHP 实现的流式 Excel 解析器，不依赖扩展（仅需 php_zip），逐行读、不缓存整表，10 万行内存占用稳定在 3–8MB，实测导入耗时压到 3 秒内。
- 安装命令（Composer）：
composer require box/spout:^3.0 - 确认
php_zip已启用：Linux/macOS 运行yum install -y php-zip或brew install php-zip；Windows 用户检查php.ini中extension=zip是否开启 - 不支持公式、样式、合并单元格——但这恰恰是它快的原因；如果你的 Excel 里有公式或复杂格式，先让运营导出为「值-only」版本再上传
怎么写一个真正能跑的导入脚本
核心逻辑就三步：校验文件 → 流式读取 → 批量入库。跳过所有中间数组组装，边读边插。
立即学习“PHP免费学习笔记（深入）”；
- 上传后先校验 MIME 类型和扩展名，别信
$_FILES['file']['name']后缀：if (!in_array($_FILES['file']['type'], ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.ms-excel'])) { die('Not an Excel file'); } - 用
ReaderFactory::createFromFile($filePath)创建 reader，调open()后直接getSheetIterator()→getRowIterator()，每行是原生数组，无类型转换干扰 - 首行当 header 构建映射：
$header = $rowIterator->current(); $map = array_flip(array_map('trim', $header));，后续每行用$rowData[$map['用户名']] ?? null提取，避免列序错位 - 数据库插入必须用事务 + 批量：
INSERT INTO user_excel (username, phone) VALUES (?, ?), (?, ?), ...，每 1000 行 commit 一次，别单条 insert
日期、数字、空值怎么处理才不翻车
Excel 内部不存 “2022-01-01”，它存的是从 1900-01-01 起的天数；数字列若含千分位或小数点后零，spout 默认返回字符串，但 MySQL 插入时可能被截断。
- 日期字段：用
\DateTime::createFromFormat('Y-m-d', date('Y-m-d', ($value - 25569) * 86400))转（$value是 Excel 序列号），或更稳妥地让前端导出时设单元格格式为「文本」 - 数字列：显式
(float) $value或filter_var($value, FILTER_SANITIZE_NUMBER_FLOAT)，避免插入'123.00'导致 MySQL 自动转成123 - 空值判断别用
empty()——Excel 空单元格读出来是''，但带空格的字符串也是''；改用trim($value) === ''
最易被忽略的一点：box/spout 不校验 Excel 内容合法性，用户传个伪造的 .xlsx（实际是 zip 包裹的恶意 XML），可能触发反序列化或 XXE。务必在 open() 前用 ZipArchive 检查根目录是否存在 [Content_Types].xml 和 xl/workbook.xml，否则直接拒收。
