WordPress WooCommerce批量导出发票Zip文件因BOM损坏问题求助

这种问题我碰到过好几次，核心原因很明确：在插件输出Zip文件内容之前，有额外的UTF-8 BOM字节被输出到了响应流里——因为FTP下载文件本身是正常的，说明压缩包在服务器上生成没问题，问题就出在PHP向浏览器发送文件的环节，有多余的字节提前跑出来了。

给你几个具体的排查和修复步骤，按顺序来大概率能解决：

• 排查带BOM的PHP文件
  UTF-8 BOM通常是某些编辑器保存文件时自动加上的，主题或插件的PHP文件如果带BOM，一旦被加载就会输出这三个字节。你可以：

  1. 用VS Code、Sublime这类编辑器打开怀疑的文件（先从发票插件本身的文件、主题的functions.php开始），右下角切换编码为UTF-8 without BOM后重新保存。
  2. 用SSH命令批量检测服务器上的文件：

     grep -r $'\xEF\xBB\xBF' /path/to/your/wp-content/themes /path/to/your/wp-content/plugins
     

     命令会列出所有带BOM的文件，逐个修正编码即可。

• 修复插件的下载输出逻辑
  找到发票插件里处理Zip下载的代码段，确保在发送文件头和输出文件内容前，清空所有输出缓冲区，并且没有任何提前输出。比如可以加上这段代码：

  // 清空所有输出缓冲区，避免之前的多余输出
  while (ob_get_level()) {
      ob_end_clean();
  }
  // 设置正确的文件头
  header('Content-Type: application/zip');
  header('Content-Disposition: attachment; filename="invoices.zip"');
  header('Content-Length: ' . filesize($zip_file_path));
  // 输出文件内容
  readfile($zip_file_path);
  // 立即终止脚本，防止后续代码输出内容
  exit;
  

  重点是ob_end_clean()会彻底清空缓冲区，exit确保脚本不会继续执行输出其他内容。

• 排查插件/主题冲突
  临时禁用除WooCommerce和发票插件外的所有其他插件，测试下载是否正常。如果恢复正常，再逐个启用插件，找到那个导致BOM输出的插件——可能是某个插件的PHP文件带BOM，或者有错误的输出逻辑。同理，切换到默认主题（比如Twenty Twenty-Four）测试，排除主题的问题。

• 检查主题的functions.php
  很多时候主题的functions.php会在<?php标签前有空格、换行，或者在?>标签后有多余的空白行，这些都会被输出到响应里。建议直接删掉functions.php结尾的?>标签（PHP允许省略这个标签），同时确保<?php前没有任何空白字符。

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