必须用phpspreadsheet替代phpexcel，安装需php≥7.4，引入iofactory/xlsx/xls类，用getrealpath()获取真实路径，校验扩展名，显式创建reader并setreaddataonly(true)，流式遍历跳过空单元格，处理日期和字符串类型及合并单元格。
在ThinkPHP项目中导入Excel文件时，必须使用PhpSpreadsheet替代已停止维护的PHPExcel，否则将遇到Class not found、日期解析失败、内存溢出或XLSX/XLS格式识别错误等问题；直接传$_FILES['tmp_name']、调用toArray()或忽略扩展名校验，会导致文件读取失败或服务崩溃。
安装与命名空间引入
执行命令安装官方推荐库，PHP版本必须≥7.4（TP6要求≥7.2，但phpspreadsheet 1.25+需7.4+，否则DateTime类加载失败）：
composer require phpoffice/phpspreadsheet
在控制器或服务类顶部，只引入实际用到的类——IOFactory用于通用加载，Xlsx/Xls用于显式控制格式，避免autoload冗余：
use PhpOffice\PhpSpreadsheet\IOFactory;
use PhpOffice\PhpSpreadsheet\Reader\Xlsx;
use PhpOffice\PhpSpreadsheet\Reader\Xls;
【Class 'PhpOffice\PhpSpreadsheet\IOFactory' not found 是最常见错误，90%因未执行 composer dump-autoload 或 vendor/autoload.php 未被TP6自动加载】
安全获取上传文件路径
ThinkPHP的think\File对象不能直接用getPathname()，该方法返回的是原始临时名（如 /tmp/phpXXXXXX），在Swoole或多进程环境下极易失效或被清理。
必须调用getRealPath()获取真实可读路径：
$file = request()->file('excel');
if (!$file || !$file->isValid()) { throw new \Exception('文件上传失败或无效'); }
$path = $file->getRealPath();
if (!is_readable($path)) { throw new \Exception('文件不可读，请检查权限'); }
仅靠$_FILES['type']判断格式不可信，客户端可伪造；必须结合原始文件名后缀校验：
$ext = pathinfo($file->getOriginalName(), PATHINFO_EXTENSION);
if (!in_array(strtolower($ext), ['xls', 'xlsx'])) { throw new \Exception('仅支持 .xls 和 .xlsx 格式'); }
按格式显式创建Reader并加载
方法一：使用Xlsx Reader（适用于.xlsx文件）
$reader = new Xlsx();
$reader->setReadDataOnly(true); // 关键：跳过样式、公式、宏，提速3倍以上且避免内存泄漏
$spreadsheet = $reader->load($path);
方法二：使用Xls Reader（适用于.xls文件）
$reader = new Xls();
$reader->setReadDataOnly(true);
$spreadsheet = $reader->load($path);
方法三：动态匹配（推荐用于混合格式入口）
switch (strtolower($ext)) {
case 'xlsx': $reader = new Xlsx(); break;
case 'xls': $reader = new Xls(); break;
default: throw new \Exception('不支持的Excel格式');
}
$reader->setReadDataOnly(true);
$spreadsheet = $reader->load($path);
流式遍历工作表，避免内存爆炸
第一步：获取活动工作表
$worksheet = $spreadsheet->getActiveSheet();
第二步：启用行迭代器，跳过空白行
$data = [];
foreach ($worksheet->getRowIterator() as $row) {
$cellIterator = $row->getCellIterator();
$cellIterator->setIterateOnlyExistingCells(true); // 关键：跳过null单元格，大幅降低内存占用
$rowData = [];
foreach ($cellIterator as $cell) {
$value = $cell->getValue();
// 合并单元格内容仅存于左上角，右侧/下方为null，需手动补全（如需）
$rowData[] = $value === null ? '' : $value;
}
if (array_filter($rowData)) { // 过滤全空行
$data[] = $rowData;
}
}
⚠️ 若表头为中文（如“用户姓名”），后续入库前必须做字段映射，数据库字段名是user_name，不映射会导致SQL错误或字段错位。
处理特殊数据类型
Excel中“2026/7/9”这类日期，在PhpSpreadsheet中默认返回Excel序列值（如45856），不是PHP时间戳。需用内置转换：
$dateValue = $cell->getFormattedValue(); // 获取格式化后的字符串，依赖单元格设置的NumberFormat
文本型数字（如工号“00123”）会被自动转为123，丢失前导零。读取时强制按字符串处理：
$value = $cell->getDataType() === \PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_STRING ? $cell->getValue() : (string)$cell->getCalculatedValue();
【合并单元格的值只存在于左上角单元格，遍历时其余位置返回null，不手动处理会导致数据错行】
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
