ThinkPHP怎样批量导入Excel 数据导入详细步骤

作者：袖梨 2026-07-21

使用 PhpSpreadsheet 实现 Excel 批量导入：先验证文件格式与大小，再流式读取避免内存溢出，清洗数据并映射字段，最后分批事务插入确保稳定高效。

你需要把 Excel 表格里的几百上千条用户信息一次性写进数据库，而不是一条条手动添加——这要求你避开内存爆掉、超时中断、字段错位、类型报错这些常见坑，直接跑通稳定可复用的导入流程。

安装并验证 phpspreadsheet 组件

执行 composer require phpoffice/phpspreadsheet 安装最新版；TP6 项目必须确保 PHP ≥ 7.4，否则类加载会静默失败。

在控制器顶部写全命名空间：use PhpOfficePhpSpreadsheetIOFactory; ——漏掉 【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() 可能返回带格式字符串，必须用 PhpOfficePhpSpreadsheetSharedDate::excelToTimestamp($raw) 转成 Unix 时间戳，再格式化为 'Y-m-d H:i:s'。