应按列名而非列序读取Excel，先扫描表头建立列名→索引映射，再通过映射安全取值；需处理空格、全角字符及同义别名，并校验必填列是否存在。
为什么直接按列顺序读 Excel 会出错
班级通信录常由老师手动整理，不同人导出的 Excel 列顺序不一致：有人把 phone 放第 2 列，有人放第 5 列；class_name 可能在 A 列也可能在 F 列。硬编码按索引取值（如 $row[1] 取电话）必然失败。
核心思路不是“读第几列”，而是“找到叫什么名字的列，再取它下面的值”。这需要先扫描表头行，建立列名 → 列索引的映射关系。
用 PhpSpreadsheet 读表头并构建列名映射
使用 PhpSpreadsheet 时，不能跳过第一行就循环数据。必须显式读取第 1 行作为表头，再遍历其单元格提取文本，生成关联数组。
-
$headerRow = $worksheet->rangeToArray('A1:Z1')[0];—— 读取首行（上限设宽些防漏列） - 用
array_flip(array_map('trim', $headerRow))快速得到['姓名' => 0, '手机号' => 1, '班级' => 2]这类映射 - 注意：Excel 表头可能含空格、全角符号或隐藏字符，
trim()和mb_convert_kana()（转全角为半角）建议加上 - 若表头含重复列名（如两个“备注”），需额外逻辑处理——只取第一次出现的位置，后续忽略或报错
按列名安全取值，避免 undefined index
有了列名映射数组 $colMap，后续每行数据就可统一用列名下标访问，彻底脱离物理位置约束。
立即学习“PHP免费学习笔记（深入）”；
// 示例：从第2行开始读数据
for ($i = 2; $i <= $highestRow; $i++) {
$row = $worksheet->rangeToArray("A{$i}:Z{$i}")[0];
$data = [
'name' => $row[$colMap['姓名'] ?? -1] ?? '',
'phone' => $row[$colMap['手机号'] ?? -1] ?? '',
'class' => $row[$colMap['班级'] ?? -1] ?? '',
];
// 插入数据库或校验...
}
关键点：$colMap['xxx'] ?? -1 防止列名不存在导致 fatal error；?? '' 避免 null 写入数据库时报错。实际项目中建议提前校验必填列是否全部存在，缺失则中断并返回明确错误，如 "缺少必要列：'姓名' 或 '手机号'"。
兼容常见表头别名（如“联系电话”“学生姓名”）
老师不会按程序员命名规范写表头。同一语义可能有多个写法：phone 对应 “电话”“联系电话”“手机”“Tel”；name 对应 “姓名”“学生姓名”“真实姓名”。硬匹配会大量失败。
- 建一个别名映射表：
$aliasMap = ['phone' => ['电话','联系电话','手机','Tel','联系手机']] - 读表头时，对每个单元格文本做模糊匹配：遍历所有别名数组，用
stripos($header, $alias) !== false判定 - 优先匹配最长关键词（如“联系电话”比“电话”权重高），避免误判
- 不建议用拼音或分词，简单字符串包含判断已覆盖 95% 场景，且稳定可控
真正难的不是代码怎么写，是拿到一份新表头时，得花时间观察老师惯用哪些词——这个“业务词典”得持续积累，否则每次换模板都得改代码。
