PHP Spreadsheet向.xlsx文件页眉插入JPEG图片不显示问题求助

问题排查与解决方法 #

核心原因（90%以上该场景问题都是这个原因） #

你只完成了页眉图片对象的注册，没有在页眉配置中添加图片渲染的特殊占位符，PHP Spreadsheet要求页眉/页脚中必须使用&G标记来指代插入的图片，否则不会触发渲染。

修正后完整代码 #

// Create a New Excel
$spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();    
$activeSheet = $spreadsheet->getActiveSheet();

$drawing = new \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooterDrawing();
$drawing->setName('PhpSpreadsheet logo');
// 转为绝对路径，避免相对路径解析异常
$drawing->setPath(realpath('app/files/images/example.jpeg'));
$drawing->setHeight(36);
$activeSheet->getHeaderFooter()->addImage($drawing, \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooter::IMAGE_HEADER_LEFT);

// 关键配置：设置奇数页页眉，&L表示左对齐，&G表示插入对应位置的图片
$activeSheet->getHeaderFooter()->setOddHeader('&L&G');
// 若需要偶数页也显示图片，添加以下配置
// $activeSheet->getHeaderFooter()->setEvenHeader('&L&G');

// 调整页面边距，避免图片高度超过页眉边距被遮挡，单位为英寸
$activeSheet->getPageMargins()->setTop(1.5);
$activeSheet->getPageMargins()->setHeader(1);

其他兼容排查点 #

• 生成文件时必须使用\PhpOffice\PhpSpreadsheet\Writer\Xlsx写入器，老版Xls格式对页眉图片的支持存在缺陷
• 打开生成的文件优先使用微软Excel验证，部分第三方办公软件（如低版本WPS）可能无法正常渲染页眉图片
• 确认图片格式为标准JPEG，部分编码特殊的JPEG图片可能无法被页眉渲染逻辑识别

内容的提问来源于stack exchange，提问作者d_codesys