如何使用ThinkPHP实现Excel数据高效批量导入？

本文共计1182个文字，预计阅读时间需要5分钟。

不直接使用ThinkPHP的该类，而是它本身不内置Excel解析能力。官方仅提供数据库和请求处理，Excel导入依赖第三方库，如phpoffice/phpspreadsheet。通过composer require phpoffice/phpspreadsheet安装后，很多人遇到自动加载失败或命名空间错误等问题。

• 别用过时的 PHPExcel，已停止维护，ThinkPHP 6+ 的 PSR-4 自动加载和它不兼容
• use PhpOffice\PhpSpreadsheet\IOFactory; 必须写全，漏掉 PhpOffice\ 前缀就报错
• 如果用的是 ThinkPHP 5.1，注意 PHP 版本不能低于 7.1；TP6 要求 PHP ≥ 7.2，而 phpspreadsheet 1.20+ 需要 PHP 7.4+
• 上传文件后，别直接传 $_FILES['file']['tmp_name'] 给 IOFactory::load() —— 它需要真实路径，且 PHP 进程要有读权限

怎么安全地读取上传的 Excel 并转成二维数组

核心是控制输入来源、限制格式、避免内存爆炸。直接 IOFactory::load($path) 读整个文件，在 10 万行 Excel 上可能吃光 512MB 内存。

• 先校验文件后缀和 MIME 类型：$_FILES['file']['type'] 是客户端传的，不可信；要用 finfo_file() 检查真实类型
• 只允许 .xlsx 和 .xls，拒绝 .csv（它不是 Excel 格式，phpspreadsheet 会解析失败）
• 用 IOFactory::createReader('Xlsx') 显式指定格式，比 load() 更快、更可控
• 读取时跳过空行：调用 $worksheet->getRowIterator() 遍历，再用 $cell->getValue() !== null 判断是否为空单元格
• 示例片段：

  $reader = IOFactory::createReader('Xlsx');<br>$spreadsheet = $reader->load($filePath);<br>$worksheet = $spreadsheet->getActiveSheet();<br>$data = [];<br>foreach ($worksheet->getRowIterator() as $row) {<br> $cellIterator = $row->getCellIterator();<br> $cellIterator->setIterateOnlyExistingCells(false);<br> $rowData = [];<br> foreach ($cellIterator as $cell) {<br> $rowData[] = $cell->getValue();<br> }<br> if (array_filter($rowData)) { // 跳过全空行<br> $data[] = $rowData;<br> }<br>}

批量插入前，为什么一定要做字段映射和数据清洗

Excel 表头可能是中文（如“用户姓名”），而数据库字段是 user_name；某列填了“是/否”，但数据库是 tinyint(1)。不做映射直接插，要么字段错位，要么触发 SQL 错误。

• 第一行必须是表头，且需硬编码映射规则，例如：['用户姓名' => 'user_name', '注册时间' => 'created_at']，不能靠“猜”
• 日期列要用 \PhpOffice\PhpSpreadsheet\Shared\Date::excelToDateTimeObject() 转，否则得到的是数字（如 44562），不是时间戳
• 手机号、邮箱要 trim() + 正则过滤空白符和全角字符，Excel 里粘贴常带不可见 Unicode 空格
• 数值列小心科学计数法：Excel 把长数字（如身份证）转成 1.23E+17，读出来就是浮点数，精度丢失——得用 $cell->getDataType() === 's' 强制当字符串读

大文件导入卡死或超时，TP 自带的 Db::transaction() 还能用吗

能用，但不是“包治百病”。事务只保证原子性，不解决内存和超时问题。10 万行一次性 insertAll()，MySQL 可能锁表几十秒，PHP 进程早被 Nginx 或 PHP-FPM 杀掉。

立即学习“PHP免费学习笔记（深入）”；

• 必须分批：每 500 行提交一次事务，用 array_chunk($data, 500) 切分，别设成 1000 或 50 —— 太小频繁提交拖慢速度，太大仍可能超内存
• 禁用模型事件：如果用了 ThinkPHP 模型，导入时关掉 event(false)，否则每个 save() 都触发 before_insert 回调，放大性能损耗
• CLI 模式下执行更稳：Web 请求有超时限制（如 Nginx 的 fastcgi_read_timeout），改用 php think import:excel /path/to/file.xlsx 命令行方式
• 别依赖 Db::getLastInsID() 获取自增 ID —— 批量插入时它只返回第一条的 ID，要 ID 列表得自己构造 INSERT ... VALUES (),(),() RETURNING id（仅 PostgreSQL）或分条插入

事情说清了就结束。真正难的不是读 Excel，是把业务规则（比如“手机号重复则跳过，邮箱为空则补默认值”）稳稳嵌进循环里，还不出错。这些逻辑一多，foreach 套三层就容易漏判条件，建议拆成独立函数，每个只干一件事。