本文详解 xlsxwriter 正确写入多个数组行的方法：需调用 writesheetheader() 初始化表头，再通过循环逐行调用 writesheetrow() 写入每组数组数据，避免仅保留最后一行的常见错误。
本文详解 xlsxwriter 正确写入多个数组行的方法：需调用 writesheetheader() 初始化表头，再通过循环逐行调用 writesheetrow() 写入每组数组数据，避免仅保留最后一行的常见错误。
在使用 XLSXWriter 库向 Excel 文件写入数据时，一个典型误区是直接将整个二维数组传给 writeSheet() 方法——这看似简洁，实则隐含限制：writeSheet($data, $sheet_name, $header) 仅接受结构严格对齐的二维数组（即每行字段数必须与表头列数完全一致），且内部实现会覆盖式处理，导致非等长数组（如 [0,'color']、[0,3,4]、['color','size']）无法正确映射，甚至仅保留最终一行。
✅ 正确做法是分步写入：先定义表头结构，再逐行写入原始数组。以下为推荐实践：
// 定义列类型映射（注意：键名应为列索引或占位符，XLSXWriter v1.x 中常用数字字符串）
$header = [
'1' => 'string',
'2' => 'string',
'3' => 'string',
'4' => 'string'
];
// 原始数据：每行是一个独立数组，长度可不一致（超出部分将被忽略，不足部分留空）
$data = [
['0', 'color'], // → 写入第1列、第2列
['0', '3', '4'], // → 写入第1、2、3列
['color', 'size'] // → 写入第1、2列
];
$writer = new XLSXWriter();
$writer->setAuthor('AUTHOR');
// 关键步骤①：初始化工作表并设置表头格式
$writer->writeSheetHeader('SHEET1', $header);
// 关键步骤②：遍历每一行数据，逐行写入（自动对齐列，自动补空/截断）
foreach ($data as $row) {
$writer->writeSheetRow('SHEET1', $row);
}
// 输出文件
$writer->writeToFile('/mnt/excel/file.xlsx');
? 注意事项与最佳实践：
- writeSheetHeader() 必须在任何 writeSheetRow() 之前调用，否则会抛出异常或写入失败；
- 表头 $header 的键（如 '1', '2'）代表列序号（从1开始），值指定该列数据类型（'string' / 'number' / 'date' 等），确保类型与实际数据匹配；
- 若某行数组长度超过表头列数，超出元素将被静默丢弃；若不足，则右侧单元格留空（不会报错）；
- 如需写入多张工作表，重复调用 writeSheetHeader() + 循环 writeSheetRow() 即可，无需重建 $writer 实例；
- 避免使用 writeSheet($data, ...) 处理非矩形数据——它适用于“表格化”二维数组（所有子数组等长），而非灵活的数据流场景。
通过这种显式、可控的逐行写入方式，你不仅能准确导出不规则数组结构，还能灵活插入空行、动态跳过脏数据、添加条件格式前缀等，大幅提升 Excel 导出模块的健壮性与可维护性。
