Yii框架如何读取Excel_Yii框架数据导入功能实现【实战】

先说几个核心判断：在Yii2项目中处理Excel，选对工具、搞清楚数据解析的坑、做好分批导入，这三件事是绕不开的关键。如果这些地方处理不当，轻则导入失败，重则内存溢出、服务崩溃——尤其在生产环境下，问题会被成倍放大。

Yii2 中读取 Excel 文件该选哪个扩展

该选哪个扩展呢？直接上 phpoffice/phpspreadsheet 就行，别碰 PHPExcel——这个包早已废弃，在 PHP 7.4+ 版本中会直接报 Class 'PHPExcel_IOFactory' not found 的错误。Yii2 本身并不内置 Excel 支持，而 phpoffice/phpspreadsheet 是当前的事实标准，兼容 .xlsx、.xls 和 .csv 格式，并且支持流式读取大文件，相当实用。

安装命令很简单：

composer require phpoffice/phpspreadsheet

常见的一个坑是：有些人安装了 phpoffice/phpexcel。这个包早在几年前就已停止维护，几乎成了技术债务的代名词。

一些补充提醒：

• 如果项目已在使用 Yii2 的 yii2-export 扩展，它的底层其实也依赖 phpspreadsheet。它的读取逻辑可以复用，但别指望用它的导出类来做导入。
• 避免在控制器里直接 new \PhpOffice\PhpSpreadsheet\Reader\Xlsx()。正确的做法是封装成一个服务类，既方便单元测试 mock，也便于后续复用和维护。
• 注意 PHP 的内存限制。如果读取一个 10MB 以上的 Excel 文件，默认是全量加载到内存中的。必须配合 setReadDataOnly(true) 和 setLoadSheetsOnly(['Sheet1']) 来限定加载范围，否则很容易内存溢出。

如何安全地解析 Excel 单元格内容（尤其日期、数字、空值）

这是最容易出事的环节。Excel 里明明显示的是 “2023-05-01”，但实际取到的值可能是一个序列号 45076；表面为空白的单元格，返回的可能是 null、空字符串，甚至是带不可见字符的 ''。如果直接调用 $cell->getValue()，结果很可能是灾难性的。

正确的做法是统一使用 getFormattedValue()，并配合类型判断：

$cell = $worksheet->getCell('A2');
$value = $cell->getFormattedValue();
if ($cell->getDataType() === \PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_NUMERIC) {
    $value = (string) $value; // 防止科学计数法转成 1.23E+10
}

几个必须注意的细节：

• 处理日期字段时，必须设置 $reader->setReadDataOnly(false)，否则日期会变成一串数字。然后通过 \PhpOffice\PhpSpreadsheet\Shared\Date::excelToDateTimeObject($value) 进行转换。
• 判断空单元格时，建议使用 trim((string)$value) === ''，而不是 empty()。后者会将 "0"、"0.0" 也视为空，这在很多业务场景下会导致误判。
• 公式单元格默认不会被计算。如果确实需要获取计算结果，可以调用 $reader->setCalculateFormulas(true)。但这样做会大幅拖慢性能，非必要建议关掉。

批量导入时怎么避免内存溢出和事务失败

把数据一次性全部读完再执行 insert 操作，这种方法在数据量超过 1 万行时就会非常危险——内存几乎是必炸的。正确的思路是边读边处理，并且严格控制事务的粒度。

推荐的模式是按 500 行分批提交，每一批开启一个独立的事务，失败只回滚本批：

$batchSize = 500;
$rows = [];
foreach ($worksheet->getRowIterator(2) as $row) { // 从第2行开始（跳过表头）
    $cells = $row->getCellIterator();
    $cells->setIterateOnlyExistingCells(false);
    $rowData = array_map(fn($cell) => $cell->getFormattedValue(), iterator_to_array($cells));
    $rows[] = $rowData;
    if (count($rows) >= $batchSize) {
        $transaction = Yii::$app->db->beginTransaction();
        try {
            YourModel::insertAll($rows); // 自定义批量插入方法
            $transaction->commit();
            $rows = [];
        } catch (\Exception $e) {
            $transaction->rollBack();
            throw $e; // 或记录日志后继续下一批
        }
    }
}

几个实战要点：

• 千万不要用 ActiveRecord 的 sa ve() 方法循环插入。每一次都会触发验证和事件，速度慢、内存占用高，完全不适合批量场景。
• insertAll() 方法需要自己实现，基于 Yii::$app->db->createCommand()->batchInsert() 构建。注意字段名必须与 Excel 列顺序一一对齐。
• 如果 Excel 行数超过 10 万，可以考虑改用 XmlReader 模式。Xlsx 本身就支持流式解析，但 Yii2 默认不会开启这个功能，需要手动配置。

上传 Excel 后怎么校验格式和业务规则

用户可能上传一个 .txt 文件，改个后缀名就叫 .xlsx；或者列顺序完全错乱。前端校验在这种场景下基本形同虚设，所有检查必须在服务端重新执行一遍。

推荐分三层进行校验：

• 文件层面：用 finfo_open(FILEINFO_MIME_TYPE) 检查真实的 MIME 类型，必须是 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 或 application/vnd.ms-excel。不能只看文件后缀。
• 结构层面：读取 Excel 的第一行，与预设字段名数组（如 ['username', 'email', 'created_at']）进行比对。只要缺失任意一项，就直接拒收。
• 数据层面：每一行数据在进入循环处理前，先执行 array_filter($rowData, 'strlen') 判断是否全为空；关键字段如 email，使用 filter_var($value, FILTER_VALIDATE_EMAIL) 进行实时校验。

错误提示必须具体，比如“第 87 行邮箱格式错误：‘abc’”，而不是笼统的“导入失败”。用户无法定位问题时，只会反复重试并抱怨——这是体验上的大忌。

真正麻烦的场景是混合类型列。比如“金额”列中既有 123.45 这样的纯数字，又有 ¥123.45 这样带符号的文本。这种情况只能靠正则清洗，库本身帮不上忙。所以，在写导入逻辑时，一定要预留这种“脏数据”的处理空间。