PHP导出Excel实战：PhpSpreadsheet库从入门到大数据量优化

后台管理系统待久了，你会发现“导出Excel”几乎是个躲不掉的硬需求。运营要日报、财务要对账、销售要客户清单，反正只要项目里存在列表数据，就一定会有人过来问：“这个能导成Excel吗？”说实话，PHP做表格导出不难，难的是做一份稳定的、格式顺眼的、大数据量不崩的Excel。我见过太多项目止步于“能跑就行”：导出来乱码、身份证变科学计数、几十万条数据直接把服务器内存打爆。这篇文章就把我在实际项目里用PHP导出Excel的完整流程拆开讲一讲，用的是目前主流推荐的PhpSpreadsheet库，从环境准备、基础导出到大数据量优化、常见坑位排查，一条线写清楚。不管你是刚接第一个后台需求的新人，还是被导出功能折磨过的老兵，都可以直接照着落地。

1. 先想清楚：PHP导出Excel到底有哪几条路

1.1 业务场景决定了方案选型

很多人一上来就搜“PHP导出Excel代码”，结果搜出来一堆老掉牙的PHPExcel教程，复制粘贴跑不通，于是开始怀疑人生。其实问题不在代码，而在选型。导出Excel这件事，看起来都是“把数组变成表格文件”，但不同业务场景下，技术选型完全不一样。

我一般会把需求先分成几类：第一类是数据量小、格式要求低，比如导出几百条用户列表给运营看一眼，这种场景追求的是“快”，别太较真格式；第二类是数据量中等、格式要求高，比如财务报表、销售对账单，列宽、边框、表头颜色、数字格式都得像样，文件名还得带上日期；第三类是数据量极大，比如几万甚至几十万条的日志导出、电商订单明细，这时候核心矛盾就不是格式了，而是内存和超时怎么控制住。

这三类需求对应的是三条完全不同的技术路线，选错了后面全是坑。我见过有人在几百条数据的项目里引入重量级库，加载就要好几秒；也见过有人用最原始的CSV方案去导十万条带样式的报表，最后样式没法控制，交付时被业务方怼得哑口无言。

1.2 三条常见路线的优缺点对比

我梳理一下PHP里做导出最常碰到的三条路线，方便你对照自己的场景做判断。

CSV方案不是说不行，它最大的问题是Excel打开CSV时中文容易乱码，除非你加BOM头，而且没法设置列宽、冻结表头、合并单元格这些东西。HTML伪装成.xls这个方案，字符串里拼一个带table标签的HTML，后缀改成.xls，Excel确实能打开，但每次打开都会弹一个“文件格式与扩展名不匹配”的警告，用户体验很糟糕，所以我基本不会在生产环境用它。

PhpSpreadsheet是PHPExcel的官方继任者，也是目前PHP生态里做Office文件读写事实上的标准方案。它的缺点是库本身比较重，需要正确安装和调优；优点是功能全、社区活跃、文档多，遇到问题基本都能搜到解决方案。

1.3 为什么最终选择PhpSpreadsheet

PHPExcel这个库在2017年左右就停止维护了，作者团队把精力都转移到PhpSpreadsheet上。新项目如果还去用PHPExcel，等于接手一个没有人维护的老代码，PHP版本一升级可能就崩给你看。PhpSpreadsheet在底层做了很多现代化改造，比如全面支持命名空间、遵循PSR标准、支持PHP 7.2以上版本（新版要求8.1+）、支持XLSX/ODS/CSV/HTML等十几种格式，而且性能比老PHPExcel有明显提升。

这里多说一句，PhpSpreadsheet的XLSX写入是标准的OpenXML格式，它内部其实是一个ZIP压缩包，里面包含一堆XML文件描述工作表、样式、共享字符串等。这个知识在排查问题的时候特别有用，比如你发现生成的xlsx文件打不开，多半就是某个XML节点出问题了。很多人在这一步直接卡死，其实换一个思路，把后缀改成.zip解压看看，大概能定位到问题到底出在工作表数据还是样式上。这个排查技巧后面会细讲。

2. 环境准备：安装PhpSpreadsheet这个库

2.1 确认自己的PHP环境

PhpSpreadsheet对PHP版本有一定要求，目前主流版本（1.x）要求PHP 7.2以上，最新的2.x版本已经要求PHP 8.1了。如果你用的是老项目，PHP还停留在5.6或者7.0阶段，建议先评估一下升级成本，而不是硬装新库。实在升不了级，只能退回去用老PHPExcel，但我还是那句话，能用新库就别抱着老库不放，安全和兼容性都是问题。

除了PHP版本，还需要确认几个PHP扩展是否已安装：ext-zip（处理XLSX压缩包必需）、ext-xml（XML解析必需）、ext-gd（如果涉及图片写入需要）、ext-mbstring（处理多字节字符串，强烈建议安装）。我用宝塔面板比较多，装完PHP之后经常发现ext-zip没开，Composer安装的时候不报错，但真正生成XLSX文件时会直接Fatal error，提示找不到ZipArchive类。这个坑我踩过，所以每次在新环境部署项目，第一件事就是跑一个php -m看看扩展列表，缺哪个装哪个。

2.2 使用Composer安装

安装方式很简单，项目根目录执行一行命令：

composer require phpoffice/phpspreadsheet

如果你的服务器在国内，Composer下载速度感人，建议先切换成阿里云镜像源：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

安装完成后，需要引入Composer的自动加载文件。如果你用的是ThinkPHP、Laravel这类框架，框架本身已经引入了vendor/autoload.php，直接用就行。如果是原生PHP项目，记得在文件顶部加上：

require_once __DIR__ . '/vendor/autoload.php';

我遇到过有的同学把PhpSpreadsheet文件夹手动下载下来丢到项目里，然后自己require各种文件，搞到最后类加载冲突。听我一句劝，这类库一定要用Composer管理，手动管理依赖在这种大型库身上就是给自己挖坑。

2.3 初始化对象与基础配置

PhpSpreadsheet的核心对象是Spreadsheet，它代表一个完整的工作簿文件。使用之前先创建一个实例：

use PhpOffice\PhpSpreadsheet\Spreadsheet; use PhpOffice\PhpSpreadsheet\Writer\Xlsx; use PhpOffice\PhpSpreadsheet\IOFactory; $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); $sheet->setTitle('订单数据');

setTitle是设置工作表名称，也就是Excel底部那个标签页的名字，默认是“Worksheet”，业务上一般会改成有意义的名称。这里还有个小细节：工作表名称不能为空、不能超过31个字符、不能包含一些特殊字符（比如* : / \ ? [ ]），如果用户输入的名称不合法，这个函数会直接抛异常，所以做动态表名的时候一定要做校验。

从这段代码开始，你已经和PhpSpreadsheet建立了联系。后续所有操作都在这个对象上展开：写入单元格、合并单元格、设置样式、导出文件等等。

3. 核心实现：写一个真正能用的导出方法

3.1 最简单的一版：把二维数组导出成Excel

先不考虑样式、不考虑性能，最基本的导出就是把一个二维数组塞进工作表里然后输出到浏览器。这个版本虽然简陋，但五脏俱全，能让你快速跑通全流程。

require_once __DIR__ . '/vendor/autoload.php'; use PhpOffice\PhpSpreadsheet\Spreadsheet; use PhpOffice\PhpSpreadsheet\Writer\Xlsx; $data = [ ['姓名', '部门', '工资'], ['张三', '技术部', 15000], ['李四', '市场部', 12000], ['王五', '运营部', 11000], ]; $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); // 从第1行第1列开始写入数据 $sheet->fromArray($data, null, 'A1'); // 设置HTTP响应头，告诉浏览器这是一个需要下载的xlsx文件 header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'); header('Content-Disposition: attachment;filename="export.xlsx"'); header('Cache-Control: max-age=0'); $writer = new Xlsx($spreadsheet); $writer->save('php://output'); exit;

这段代码跑通之后，浏览器会直接下载一个名为export.xlsx的文件，打开就能看到三行数据。fromArray方法可以传入一个二维数组，第二个参数是空值占位符（默认null时留空），第三个参数指定起始单元格位置。

我提几个容易忽略的点。第一，header必须在任何输出之前设置，包括HTML标签、空行、甚至是编辑器在文件头部留下的BOM头，否则会出现“文件已损坏”的提示。第二，save('php://output')是把文件内容直接输出到HTTP响应流里，这比先保存到临时文件再读取要干净利落。第三，导出结束后最好加上exit;，防止后续代码输出干扰文件内容。上面这段代码末尾的exit就是干这个用的。

3.2 动态表头：让字段顺序和列名可以配置

实际业务中，导出的字段往往不是写死的。用户可能勾选了“姓名、部门、工资”三列，也可能勾选了“姓名、工号、入职时间、工资”四列，甚至同一个导出接口要复用给多个业务模块。写死列名的方式没法应对这种变化，所以第二步就是把表头配置化。

我封装一个方法，接收两个参数：一个是字段映射配置，定义哪些字段要导出、中文列名叫什么；另一个是原始数据数组。这样调用方只需要关心“我要导哪些字段”，不需要关心Excel怎么排版。

/** * 根据字段配置导出数据 * * @param array $fields 字段映射，如 ['name' => '姓名', 'salary' => '工资'] * @param array $rows 原始数据，如 [['name' => '张三', 'salary' => 15000]] * @param string $filename 导出的文件名 */ function exportWithFields(array $fields, array $rows, string $filename) { $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); // 写入表头 $colIndex = 1; foreach ($fields as $field => $label) { $sheet->setCellValueByColumnAndRow($colIndex, 1, $label); $colIndex++; } // 写入数据 $rowIndex = 2; foreach ($rows as $row) { $colIndex = 1; foreach ($fields as $field => $label) { $value = $row[$field] ?? ''; $sheet->setCellValueByColumnAndRow($colIndex, $rowIndex, $value); $colIndex++; } $rowIndex++; } // 输出文件（代码见上面，略） }

使用的时候，配置一次字段映射即可：

$fields = [ 'name' => '姓名', 'dept' => '部门', 'salary' => '工资', ]; exportWithFields($fields, $userList, '员工工资表.xlsx');

这个封装有几个好处：字段顺序由$fields数组决定，想调整顺序改配置就行；新增字段只要在映射里加一行；数据数组里没有的字段会用空字符串兜底，不会报错。我把setCellValueByColumnAndRow换成数字行列索引方式，主要是为了方便循环遍历，不用去拼A1、B1、C1这种字符串。

3.3 样式与列宽：告别默认表格的粗糙感

业务方对导出的要求往往是“像人工做的一样”。默认导出的表格没有列宽自适应，所有列挤在一起，数字多的列会被截断显示成###，表头和正文也分不清层次。这一节就说清楚样式怎么加。

先上代码，再逐行解释：

use PhpOffice\PhpSpreadsheet\Style\Color; use PhpOffice\PhpSpreadsheet\Style\Fill; use PhpOffice\PhpSpreadsheet\Style\Border; use PhpOffice\PhpSpreadsheet\Style\Alignment; // 设置自动筛选和冻结首行 $sheet->setAutoFilter('A1:' . $sheet->getHighestDataColumn() . '1'); $sheet->freezePane('A2'); // 设置列宽，A列20个字符宽度，B列15，C列12 $sheet->getColumnDimension('A')->setWidth(20); $sheet->getColumnDimension('B')->setWidth(15); $sheet->getColumnDimension('C')->setWidth(12); // 表头样式：背景色、字体加粗、居中、白色文字 $headerStyle = [ 'font' => [ 'bold' => true, 'color' => ['argb' => Color::COLOR_WHITE], ], 'fill' => [ 'fillType' => Fill::FILL_SOLID, 'startColor' => ['argb' => 'FF4472C4'], ], 'alignment' => [ 'horizontal' => Alignment::HORIZONTAL_CENTER, 'vertical' => Alignment::VERTICAL_CENTER, ], ]; $sheet->getStyle('A1:C1')->applyFromArray($headerStyle); // 正文区域加边框，垂直居中 $bodyStyle = [ 'borders' => [ 'allBorders' => [ 'borderStyle' => Border::BORDER_THIN, ], ], 'alignment' => [ 'vertical' => Alignment::VERTICAL_CENTER, ], ]; $sheet->getStyle('A2:C' . $sheet->getHighestDataRow())->applyFromArray($bodyStyle); // 表头行高设置，更大气 $sheet->getRowDimension('1')->setRowHeight(28);

这里面有几个细节值得展开说。setAutoFilter会启用Excel的筛选功能，但必须保证筛选区域的表头行数据正确；我这里是按数据区域最大列数动态计算的，但如果数据为空，这个区域就定位不准，所以代码里最好加一个行数判断。freezePane('A2')实现了“下拉数据时首行始终可见”的效果，对数据量大的表格非常友好。

颜色的写法要说明一下，FF4472C4是ARGB格式，前面两位FF代表完全不透明，后面六位才是RGB。如果你只写六位，PhpSpreadsheet有时会自行补全，但为了保险，我习惯统一写成八位。边框的BORDER_THIN是细实线，报表里最常用，不需要用粗线。

这个阶段的导出，已经能满足绝大多数管理后台的“体面导出”需求了。

3.4 写一个可复用的导出类

到这一步，可以整合前面的代码，写一个专门负责导出的类。这类工具类在每个项目中几乎都是刚需，值得维护得干净一点。

namespace App\Utils; use PhpOffice\PhpSpreadsheet\Spreadsheet; use PhpOffice\PhpSpreadsheet\Writer\Xlsx; class ExcelExporter { /** * 导出带表头的数组数据 */ public function exportWithHeader(array $headers, array $rows, string $filename): void { $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); // 表头 foreach (array_values($headers) as $index => $header) { $sheet->setCellValueByColumnAndRow($index + 1, 1, $header); } // 数据 $rowIndex = 2; foreach ($rows as $row) { foreach (array_values($row) as $colIndex => $value) { $sheet->setCellValueByColumnAndRow($colIndex + 1, $rowIndex, $value); } $rowIndex++; } // 自动列宽估算 foreach (array_keys($headers) as $index => $field) { $colLetter = \PhpOffice\PhpSpreadsheet\Cell\Coordinate::stringFromColumnIndex($index + 1); $maxLen = mb_strlen((string)$headers[$field]); foreach ($rows as $row) { $len = mb_strlen((string)($row[$field] ?? '')); if ($len > $maxLen) { $maxLen = $len; } } $sheet->getColumnDimension($colLetter)->setWidth(min(max($maxLen + 2, 8), 50)); } $this->output($spreadsheet, $filename); } /** * 输出xlsx文件到浏览器 */ private function output(Spreadsheet $spreadsheet, string $filename): void { $filename = preg_replace('/[\/:*?"<>|]/', '_', $filename); header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'); header('Content-Disposition: attachment;filename="' . $filename . '"'); header('Cache-Control: max-age=0'); $writer = new Xlsx($spreadsheet); $writer->save('php://output'); exit; } }

这段代码里，我非常推荐自动列宽估算这一段。虽然PhpSpreadsheet自带getColumnDimension()->setAutoSize(true)方法，但实际效果并不稳定，尤其遇到中文和长文本时经常估算不准。我用的方式是遍历数据统计每列最长字符数，然后限制在8到50之间，超出50的列自动截断宽度，这样导出的表格打开后基本不需要手动调整列宽。

注意output方法里对文件名做了非法字符替换。Windows系统不允许文件名包含\/:*?"<>|这些字符，如果业务系统里导出的文件名带有斜杠或冒号（比如命名成“2024/2025年度报表.xlsx”），浏览器会报错或者下载成乱码名，这里提前清洗一下就能避免很多诡异的问题。

4. 大数据量导出的处理：内存与超时优化

4.1 为什么会内存爆掉

这是导出功能最经典的一个坑。一开始你导几百条数据没事，导几千条也没事，上线跑了一阵子之后运营导一个月的数据，服务器直接内存溢出，页面白屏，日志里写着Allowed memory size of 134217728 bytes exhausted。

原因在于PhpSpreadsheet在内存中构建完整的工作簿对象，所有单元格、样式、字符串都保存在PHP内存里。官方文档明确标记了单元格占用的内存大约为1KB/个，听起来好像不多，但你算一笔账：一万行乘以三十列，三十万个单元格，光单元格对象就吃掉将近300MB内存；再加上共享字符串、样式缓存、对象开销，跑个几万行的导出轻松超过PHP默认的128MB内存限制。

有人可能会说“那我把内存限制调大不就行了？”，ini_set('memory_limit', '1024M')确实能救急，但这是治标不治本。几十万行、上百列的数据，给多少内存都不够造的。真正的问题在于一次把所有数据加载进内存，而不是加载的复杂度本身。

4.2 两个思路：减少内存 vs 分批写入

解决大数据量导出，我总结下来有两个核心思路，可以组合使用。

第一个思路是给PhpSpreadsheet“减负”。如果不需要公式计算，关闭公式计算可以省一部分性能开销：

\PhpOffice\PhpSpreadsheet\Calculation\Calculation::getInstance()->setCalculationEngineEnabled(false);

第二个思路是数据侧分批处理。不要一次性从数据库把全量数据加载到内存，而是用生成器逐批取数，写一批到Excel后就释放一批。这也是我最常用的方案。

/** * 分批从数据库取数并写入Excel，适合大结果集 */ function exportLargeData($dbQuery, string $filename): void { $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); // 手动写入表头 $headers = ['ID', '用户名', '创建时间']; foreach ($headers as $col => $label) { $sheet->setCellValueByColumnAndRow($col + 1, 1, $label); } $rowIndex = 2; $pageSize = 1000; $page = 1; do { $rows = $dbQuery->page($page, $pageSize)->select(); // 伪代码，以你项目实际查询为准 if (empty($rows)) { break; } foreach ($rows as $row) { $sheet->setCellValueByColumnAndRow(1, $rowIndex, $row['id']); $sheet->setCellValueByColumnAndRow(2, $rowIndex, $row['username']); $sheet->setCellValueByColumnAndRow(3, $rowIndex, $row['created_at']); $rowIndex++; } unset($rows); // 及时释放变量 $page++; // 每批数据写入后ultra缓存清理（具体根据框架调整） if (function_exists('gc_collect_cycles')) { gc_collect_cycles(); } } while (count($rows) > 0); // 输出文件 (new Xlsx($spreadsheet))->save('php://output'); exit; }

这里分页大小$pageSize选1000是比较稳妥的值，一次拉太多内存压力大，一次太少数据库查询次数多。unset($rows)加上gc_collect_cycles()是我处理内存释放的习惯动作，尤其在循环体内有大量字符串拼接时，能感受到明显的内存回收效果。

另外，对于确实超大的导出，还有一个思路是改用CSV格式输出。CSV本质是纯文本流，可以边读数据库边写文件，内存占用几乎忽略不计。如果业务方不强制要求.xlsx，完全可以给出“下载CSV（用Excel打开）”的方案，大数据量场景下这个方案性价比最高。

4.3 流式输出与HTTP响应头的配合

很多项目里导出响应慢，不完全是PHP慢，还有一个原因是PHP把所有数据生成完毕后一次性输出到浏览器，用户在此期间什么都看不到，体验非常差。

PhpSpreadsheet的Writer默认会把整个文件内容构建在内存中，然后再一次性输出。想要边生成边下载，没想象中简单，因为XLSX本质是ZIP压缩包，必须先知道所有内容才能算压缩，没法做到真正的流式。折中方案是：数据分页写入，把生成时间均摊开，同时把内存峰值压住，最后一次性输出时用户最多等几秒，这个体验是能接受的。

配合输出缓冲处理，推荐在save('php://output')前清理所有缓冲区：

while (ob_get_level() > 0) { ob_end_clean(); }

Why？因为框架或者项目里可能提前开启过输出缓冲，残留内容会被一并输出到文件流里，直接导致生成的XLSX文件打不开。这个问题在前面的“下载文件损坏”场景里非常常见，先清理缓冲再输出是个保险动作。

执行时间方面，超过30秒会超时，可以动态设置：

set_time_limit(0);

但别滥用。我建议只在大数据量导出的方法里临时延长执行时间，不要全局放开。如果某次导出超过300秒还没完成，多半不是执行时间问题，而是数据库查询慢或者死循环，这时候应该查SQL和逻辑，而不是无限放宽时间限制。

5. 常见问题与排查技巧实录

5.1 表格打开乱码

乱码问题最常见的场景是：用Excel打开CSV或老式XLS文件，中文全部变成“鍚夌淮”这种天书字符。原因基本就两类：文件编码不是UTF-8，或者UTF-8文件缺少BOM头。

如果是CSV导出，用fputcsv时默认不会写BOM，而Windows版的Excel对无BOM的UTF-8文件识别经常出错，Excel会自作主张按GBK解码，于是中文全乱。解决办法是在输出CSV前先输出三个字节的BOM：

echo "\xEF\xBB\xBF"; // UTF-8 BOM

如果是用PhpSpreadsheet导出XLSX，基本不存在编码问题，因为XLSX内部统一是UTF-8 XML格式，Excel能正常解析。在XLSX里出现乱码，通常是你手动给单元格塞了非法编码的字符串，比如从GBK编码的老系统读取的数据没转码，就直接写入单元格。解决方案是入库和读取时统一转成UTF-8，不要到导出环节才临时转。

5.2 下载文件提示损坏或无法打开

这是我被问得最多的问题，没有之一。症状是浏览器文件下载下来了，但打开时Excel提示“文件格式和扩展名不匹配”或者“文件已损坏，是否尝试修复”。

原因一般逃不出这几种。第一，输出文件前有意外输出，比如PHP文件开头有个空格、某个include的文件里有BOM头、之后echo了两个换行，这些垃圾字节混进xlsx文件前面，ZIP格式辨认失败就报损坏。第二，header里指定了错误的Content-Type，有些老教程写application/vnd.ms-excel，那是给老版本XLS用的，生成XLSX时得用application/vnd.openxmlformats-officedocument.spreadsheetml.sheet。第三，引入了多个缓冲区没清理，前面框架输出的页面内容混入文件流。

排查技巧：先用编辑器以二进制方式打开下载的文件，看最前面几个字节是不是PK。PK是ZIP文件的标准魔数，XLSX本身就是ZIP压缩包，如果看到PK就说明结构正常，问题多半出在内容XML上；如果前面出现了<html>、<!DOCTYPE甚至空行，那就看输出环节哪一步混进去了。

5.3 长数字变成科学计数法，身份证号末尾变000

这个坑在导出用户表、身份证、银行卡号时必现。Excel默认把纯数字当数值处理，超过一定长度就自动显示为科学计数法（比如1.23457E+17），就算你单元格里实际存的值是对的，但用户看到的就是一串乱码；更糟的是如果精度不足，最后几位还会被舍入成0，数据直接错误。

解决办法有两个方向。一是写入数据时明确指定单元格类型为字符串：

use PhpOffice\PhpSpreadsheet\Cell\DataType; $sheet->setCellValueExplicit('A2', '110101199001011234', DataType::TYPE_STRING);

这样做的好处是即使单元格里是一长串数字，Excel也会按文本展示，不再触发科学计数法转换。缺点是这个单元格左上角可能会出现一个绿色的“数字以文本形式存储”提示，但实际使用中影响不大。

第二个方向是写入时在数字前加一个不可见的撇号'，老式PHPExcel时代很多老教程这么教，但PhpSpreadsheet里这个做法不如setCellValueExplicit干净，我建议直接用上面的方案。如果数据里既有数字又有文本，最稳妥的方法是先把列设置成文本格式，再写入数据：

$sheet->getStyle('A2:A1000')->getNumberFormat() ->setFormatCode(\PhpOffice\PhpSpreadsheet\Style\NumberFormat::FORMAT_TEXT); $sheet->setCellValueExplicit('A2', $value, DataType::TYPE_STRING);

5.4 特殊字符导致XML解析错误，文件打开后报错内容为空

有一种很隐蔽的损坏：文件能下载，打开时Excel提示“发现无法读取的内容，是否尝试恢复”，点击恢复后有部分数据丢失，或者直接打不开。

原因一般是某个单元格里包含XML非法字符。Excel的XLSX格式用了XML，而XML标准不允许出现某些控制字符，比如ASCII码为0到8的字符（\x00到\x08）、\x0B、\x0C、\x0E到\x1F这些。如果数据库里存储了这类二进制控制字符（比如从某个上传文件解析出来的内容），写入单元格后，生成的XML就会非法。

解决办法是在写入前过滤这些字符。我封装一个小方法：

function sanitizeXmlValue($value) { if (is_string($value)) { // 移除XML 1.0不允许的控制字符 $value = preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F]/', '', $value); } return $value; }

这里有个细节：\x7F（DEL字符）虽然在一些XML规范里也建议去掉，但实际Excel能处理，所以我没有列入过滤范围。把数据都过一次这个方法再去写入，基本能杜绝这类问题。

5.5 一个排查速查表

6. 从实际项目里攒下来的几个小经验

要说导出功能，代码只是一部分，真正决定体验的往往是细节。我在多个项目里导过几十万行的表，踩了不少坑，捡几个最有通用性的经验说说。

命名文件时，建议带上日期时间，不然下载次数多了之后用户桌面全是“导出.xlsx”，根本分不清哪次是哪次。命名时如果文件名里包含中文，部分浏览器会下载成乱码文件名，我一般是给文件名做一次URL编码：rawurlencode($filename)，这样无论是Chrome、Edge还是老版IE，都能正确显示。当然如果你用前面那个可复用类，文件名已经做了非法字符清洗，再加个编码更稳。

日期时间字段写入Excel时有个有趣的问题：如果直接把2024-08-01 12:30:00这样的字符串写到单元格，Excel会识别成文本而不是日期。想要真正的日期格式，可以把值转成Excel的时间戳数字，再给单元格设置日期格式：

use PhpOffice\PhpSpreadsheet\Shared\Date; use PhpOffice\PhpSpreadsheet\Style\NumberFormat; $cell = $sheet->getCell('A2'); $cell->setValue(Date::PHPToExcel(strtotime('2024-08-01 12:30:00'))); $sheet->getStyle('A2')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_DATE_DATETIME);

但这样做有一个坑：PHPToExcel方法依赖服务器的时区设置。如果项目设置了其他时区而系统和PHP时区不一致，转换出来的日期会偏移几个小时。我一般会先统一项目时区，再调用这个转换方法，避免导出数据出现时间偏差。

最后再分享一个小技巧：导出量很大时，不要等导出完全结束才给用户反馈，尤其是Web界面。可以在页面里加一个“导出任务已创建，请稍后刷新页面查看下载链接”的提示，后台用计划任务生成文件存到临时目录。这种异步导出的方案大幅度提升了用户体验，也把接口超时的风险转移到了可控范围内。当然，这是架构层面的事了，等你的项目数据量真到了那个量级，自然会觉得这一步非做不可。

我在实际使用中的体会是，PHP导出Excel这件事难不在写代码，而在于你对整个数据流有完整的掌控：数据库查到什么、内存怎么释放、有什么脏数据混进来、HTTP输出干不干净。把这几个环节都想清楚了，导出一个百万行、带格式、能秒开的Excel也不是什么玄学。