本文详解 xlsxwriter 正确写入多维数组数据的方法：避免仅写入最后一组数据的常见错误，通过 writesheetheader() + 循环调用 writesheetrow() 实现逐行追加，确保所有数组元素完整、对齐地落表。
本文详解 xlsxwriter 正确写入多维数组数据的方法：避免仅写入最后一组数据的常见错误，通过 writesheetheader() + 循环调用 writesheetrow() 实现逐行追加，确保所有数组元素完整、对齐地落表。
在使用 XLSXWriter 库将 PHP 数组写入 Excel 文件时，一个典型误区是误用 writeSheet($data, $sheetName, $header) —— 该方法要求 $data 是二维关联数组或索引数组的集合，且底层会以“覆盖式”方式处理数据结构；若传入非标准格式（如长度不一的嵌套索引数组），库可能仅保留最后一次写入行为，导致仅最后一行数据生效。
正确做法是分离表头定义与数据写入流程：先用 writeSheetHeader() 声明列结构，再通过循环逐行调用 writeSheetRow() 写入每一条记录。这种方式完全可控，支持变长行（自动以空值补位）、类型推断准确，并天然适配动态生成的数据集。
以下为完整可运行示例：
<?php require_once 'vendor/autoload.php'; // 确保已引入 XLSXWriter
$header = [
'1' => 'string',
'2' => 'string',
'3' => 'string',
'4' => 'string'
];
// 源数据：每个子数组代表 Excel 中的一行（允许列数不等）
$data = [
['0', 'color'], // → 写入第1行：A1="0", B1="color", C1/D1为空
['0', '3', '4'], // → 写入第2行：A2="0", B2="3", C2="4", D2为空
['color', 'size'] // → 写入第3行：A3="color", B3="size", C3/D3为空
];
$writer = new XLSXWriter();
$writer->setAuthor('AUTHOR');
// ✅ 正确：先声明表头结构（列名+类型）
$writer->writeSheetHeader('SHEET1', $header);
// ✅ 正确：逐行写入，每行自动按 header 对齐，缺失列填 null
foreach ($data as $row) {
$writer->writeSheetRow('SHEET1', $row);
}
// 输出文件
$filename = '/mnt/excel/file.xlsx';
$writer->writeToFile($filename);
echo "✅ Excel 文件已生成：{$filename}\n";
?>
⚠️ 关键注意事项：
- writeSheetHeader() 中的键（如 '1', '2'）对应 Excel 列序号（从 1 开始），值指定该列默认数据类型（'string'/'number'/'date' 等），影响单元格格式与公式兼容性；
- writeSheetRow() 会严格依据 header 定义的列数进行对齐：若某行元素少于列数，右侧自动补空；若多于列数，超出部分将被静默截断（无警告），请提前校验数据结构；
- 不要混用 writeSheet() 和 writeSheetRow() 向同一 sheet 写入——前者会重置内部状态，导致后者失效；
- 如需写入多张工作表，对每张 sheet 独立调用 writeSheetHeader() + 多次 writeSheetRow() 即可。
总结：XLSXWriter 的设计哲学是「流式写入」而非「内存全量构建」，因此推荐始终采用 Header + Row 的分步模式。它不仅解决多数组写入遗漏问题，还显著降低内存占用，适用于导出万级行数据的生产场景。
