PHPWord是PHP生成.docx最稳方案，需用composer require phpoffice/phpword安装，样式参数必须传数组（如['bold'=>true]）、中文字体显式指定、设正确header、图片用绝对路径或data URI、大数据量后及时unset释放内存。
PHPWord 是目前 PHP 生成 .docx 最可靠的选择，不依赖外部服务或系统组件，纯 PHP 实现，但它的 API 行为和常见预期有明显差异——直接照搬 HTML 或 CSS 思维写样式、漏设 header、传错参数类型，90% 的“导出失败”“文件损坏”“样式不生效”都源于此。
安装和初始化必须用 phpoffice/phpword，不是 phpword
Composer 安装命令必须写全命名空间：
composer require phpoffice/phpword
如果只写 composer require phpword，会装错包（那个是过时的 fork，已多年未维护）。初始化时也得用完整类名：
-
use PhpOffice\PhpWord\PhpWord;—— 正确 -
use PHPWord;或new PHPWord()—— 类不存在，报Class 'PHPWord' not found
addText() 和 addTable() 的样式参数必须是数组，不能是字符串
很多人写 $section->addText('标题', 'bold')，结果文字毫无加粗效果。这是因为 PHPWord 所有样式参数都是关联数组，键名严格区分大小写、且必须匹配 OpenXML 规范定义：
立即学习“PHP免费学习笔记（深入）”；
- 加粗要写
['bold' => true]，不是'bold'或['Bold' => true] - 中文字体必须显式指定，如
['name' => 'SimSun', 'size' => 16]，否则默认用 Calibri，中文显示为空白或方块 - 表格边框需完整声明：
['borderSize' => 12, 'borderColor' => '000000']，漏掉borderSize就等于没边框
常见错误现象：文字全变小五号宋体、表格无边框、中文乱码 —— 全部指向样式数组缺失、键名拼错或字体名未设。
导出前必须设置正确 header，且不能有任何额外输出
浏览器下载 .docx 文件，靠的是两个关键响应头：
header('Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document');header('Content-Disposition: attachment; filename="report.docx"');
缺一不可。更关键的是：$objWriter->save('php://output') 前后绝对不能有 echo、var_dump、print_r，甚至不能有 PHP 文件末尾多余的换行或空格 —— 任何字符都会污染二进制流，导致 Word 提示“文件已损坏”。
调试时建议先保存到磁盘：$objWriter->save('/tmp/test.docx')，确认内容正常后再切回 php://output。
大数据量导出必须手动 unset()，否则内存爆掉
PHPWord 把整个文档结构存在内存里，生成含图片+千行表格的文档时，对象常占 150MB 以上。Apache 或 Nginx 下容易触发 Fatal error: Allowed memory size exhausted。
这不是配置问题，是设计使然（它不支持流式写入）。解决方式很明确：
- 在
$objWriter->save('php://output')后立刻执行：unset($phpWord); unset($section); unset($objWriter); - 如果用了临时目录（比如
Settings::setTempDir('./tmp')），也要确保该目录可写且有足够空间 - 不要试图靠
ini_set('memory_limit', '512M')硬扛 —— 内存峰值仍可能突破限制，且影响并发能力
真正容易被忽略的点是：图片路径必须是绝对路径或 data: URI。addImage('uploads/logo.png') 这种相对路径必然失败，显示红叉 —— 因为 PHPWord 不解析当前工作目录，只认完整路径或 base64 编码内联。
