PHP 解析 Excel 的那些坑：一次“行号错位”引发的数据丢失

一、问题回放

最近排查一个线上接口：程序从一个 Excel 价格表里按行读取数据，结果发现某些行死活读不出来------用 Excel 打开明明看得到值，程序却当它不存在。

最初怀疑是"从第几行开始取"的判断写错了，但反复核对行号逻辑都没问题。最终定位到真正的元凶：

解析库默认会"跳过空行"，导致程序里的行下标和 Excel 里肉眼数出来的真实行号对不上------也就是"行号错位"。

这是 PHP（其实各语言都一样）解析 Excel 时一个极其常见、又极其隐蔽的坑。下面就围绕它，系统讲讲 PHP 读 Excel 时容易踩的几类陷阱。

二、核心坑：空行被默认跳过 → 行号错位

坑是怎么产生的

PHP 生态里常用的 Excel 解析方案大致有三类：

PhpSpreadsheet：功能最全，把整个表格读进内存；
OpenSpout（原 box/spout）：流式读取，省内存、快；
Spatie SimpleExcel：对 OpenSpout 的封装，API 更顺手。

其中流式读取的引擎（OpenSpout / SimpleExcel）默认就会丢弃"整行为空"的行。问题在于，我们写代码时几乎都会下意识地假设：

php 复制代码

foreach ($rows as $index => $row) {
    // 潜意识：$index == 0 就是第 1 行，$index == 9 就是第 10 行
}

可一旦表格里夹着空行（表头与数据之间的空白行、分隔行、合并单元格留下的空行......），这些行被引擎默默吃掉后，$index 的含义就从"Excel 的第几行"悄悄变成了"第几条非空记录"。

于是这种很常见的写法就崩了：

php 复制代码

foreach ($rows as $index => $row) {
    if ($index < 9) continue;   // 想跳过前 9 行表头，从第 10 行开始
    // ... 处理数据
}

你以为 $index = 9 对应 Excel 第 10 行，实际上中间只要少了 N 个空行，真正落到的就是第 10 + N 行。结果就是：要么读错了行，要么把你真正想要的那一行整个跳过。最坑的是它不报错，只是结果悄悄少了几行。

验证方法

判断是不是踩了这个坑，最快的办法是把读出来的总行数和 Excel 实际行数对一下：

php 复制代码

$rows = SimpleExcelReader::create($file)->noHeaderRow()->getRows()->toArray();
echo count($rows); // 如果明显小于 Excel 真实行数，基本就是空行被跳过了

三、衍生坑：与"空行"纠缠在一起的几个问题

"行号错位"往往不是单独出现的，它常常和下面几个坑叠加，互相放大。

1. 合并单元格让"看着有值的行"变成空行

Excel 的合并单元格，底层只在左上角那一格存值，其余格子物理上是空的。流式引擎不会还原合并关系，于是：

合并区域的非左上角行，关键列读出来是空字符串；
如果一整行都落在合并的空白区，它就成了"全空行"，进而被引擎跳过------又喂给了上面的"行号错位"。

所以合并单元格不仅会让单元格读空，还会间接制造空行，是"行号错位"的重要帮凶。

2. "看起来空"其实不空

有些行肉眼看是空的，实际上含有空格、不可见字符，或带格式但无内容的单元格。不同库对"什么算空行"判定不一样：有的只要有格式就算非空，有的要内容真为空才算。这会导致同一个文件，换个库读出来的行数都不一样，行号错位的表现也跟着变。

3. 列也会"错位"

和行同理，前导空列、被合并的列 也会让你用数字下标取列时拿错数据。$row[3] 到底是第几列，取决于库是否补齐空列、是否从 A 列算起。

4. 数字、日期、科学计数法的类型陷阱

这虽然不是"空行"问题，但同属 Excel 解析高频坑，顺带提一句：

长料号、订单号会被读成科学计数法（1.23E+12）或丢失前导零；
日期可能被读成 Excel 的序列号数字（如 45000）而不是日期字符串；
金额可能因浮点精度出现 9.9999999 这种尾差。

对"主键类"字段，最好强制按字符串读取，不要让库自作主张去推断类型。

四、怎么避坑

原则：不要相信"循环下标 == Excel 行号"

只要表格里可能有空行、合并行、隐藏行，循环下标的含义就不可靠。需要按行号定位时，一定要用库能给出的"真实行坐标"，而不是 foreach 的自增下标。

方案一：用 PhpSpreadsheet 按真实坐标读

PhpSpreadsheet 不会偷偷丢空行，可以直接按 Excel 的真实行号遍历，行号一一对应：

php 复制代码

$sheet = \PhpOffice\PhpSpreadsheet\IOFactory::load($file)->getSheet(0);

$highestRow = $sheet->getHighestRow();
for ($rowNumber = 10; $rowNumber <= $highestRow; $rowNumber++) {
    // $rowNumber 就是 Excel 真实行号，绝不会因空行而错位
    $key = $sheet->getCell('A' . $rowNumber)->getValue();
    // ...
}

它还能顺便读到合并单元格信息，把左上角的值填充回整个合并区，从根上解决"合并制造空行/空值"的问题。代价是全量加载、内存占用高，大文件要留意性能。

方案二：继续用流式库，但显式保留空行

如果出于性能必须用流式引擎，就显式关闭"跳过空行" ，让下标重新和真实行号对齐。OpenSpout 提供了相应选项（如 setShouldPreserveEmptyRows(true)），SimpleExcel 也可通过底层配置达到类似效果。保留空行后，再在循环里自己判断、跳过即可------关键是让你掌控跳过逻辑，而不是交给库默默处理。

方案三：源头治理

如果这张表本来就是"给程序读"的，最好在数据交换约定上就规避这些坑：

数据区不要用合并单元格；
表头和数据区之间不要留空行，或干脆约定固定的起始行；
主键列保证无空值、无合并、纯文本。

合并单元格、花式表头服务的是"人看"的排版，却给"机器读"制造了大量歧义。能在源头约束，远比事后到处打补丁划算。

五、小结

PHP 读 Excel 看似简单，真正的坑大多不在你的业务代码，而在解析库对"边界情况"的默认行为上：

流式库默认跳过空行 → 循环下标不再等于 Excel 行号（本次事故的真凶）；
合并单元格只存左上角值，还会间接制造空行；
"看起来空"的判定因库而异，列也会同样错位；
数字/日期/前导零的类型推断容易把关键字段读坏。

一句话记住：当你确信代码逻辑没错却拿不到数据时，先怀疑"数据的形状"有没有被解析库的默认行为悄悄改变。 需要靠行号定位时，永远使用库提供的真实坐标，别信 foreach 的自增下标。

需要的话，我可以把这篇整理成 Markdown 文件保存到当前目录，方便你直接发布。告诉我文件名即可。