PHPWord中文乱码及使用问题需三步解决：一是用完整命名空间new \PhpOffice\PhpWord\PhpWord()并引入autoload；二是addText()中显式设中文字体（如'SimSun'）和语言（'zh-CN'）；三是导出前清空输出缓冲、设置正确header且禁用BOM。
phpoffice/phpword 不是“装上就能用”的库，很多问题出在安装后没对齐命名空间、没设字体、或输出时污染了二进制流。直接运行 composer require phpoffice/phpword 只是第一步，真正卡住的地方在后续调用。
为什么 new PhpWord() 报 Class not found？
常见错误不是 Composer 没装好，而是类名写错或 autoloader 没生效：
- 必须用完整命名空间：
new \PhpOffice\PhpWord\PhpWord()，不能简写为new PhpWord()（除非已use PhpOffice\PhpWord\PhpWord） -
use PhpWord\PhpWord是旧版写法，v1.0+ 已失效，会报错 - 确认
vendor/autoload.php已被引入；如果用框架（如 Laravel），通常自动加载，但 CLI 脚本必须手动require_once 'vendor/autoload.php' - 执行
composer dump-autoload强制刷新映射，尤其在手动改过类文件或迁移到新环境后
中文显示方块或样式全丢，怎么办？
PHPWord 默认不嵌入中文字体，也不设语言属性，Word 打开时按西文逻辑渲染，结果就是乱码或默认宋体小五号：
- 每个
addText()都要显式传字体：例如$section->addText('你好', ['font' => 'SimSun'], ['lang' => 'zh-CN']) - 推荐用
'SimSun'（宋体）或'Microsoft YaHei'（微软雅黑），避免用'sans-serif'这类通用名 - 保存格式必须是
'Word2007'（即 .docx），'Word2003'根本不支持 UTF-8 和多数样式 - 别依赖 Word 自动识别编码——它不会读 PHP 文件的 UTF-8 BOM，也不会猜你用的是简体中文
导出后提示“文件已损坏”或打不开？
绝大多数是 HTTP 响应体被意外内容污染，不是代码逻辑错：
- 检查是否有
echo、var_dump、print_r或空白行在$writer->save('php://output')之前执行 - 确保没有 UTF-8 BOM 字节：用 VS Code 或 Sublime 看文件编码，选 “UTF-8 without BOM” 保存 PHP 文件
- 若用
php://output，必须提前设置 header：header('Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document')和header('Content-Disposition: attachment; filename="report.docx"') - 大文件别用
echo file_get_contents($path)，改用readfile($path); exit;，否则内存溢出
生成慢、内存爆掉、千行表格卡死？
PHPWord 是内存驻留式构建，不是流式写入，文档越大，对象树越深，内存占用呈非线性增长：
立即学习“PHP免费学习笔记（深入）”；
- 生成完立即
unset($phpWord)，别等脚本结束才释放 - 避免在循环里反复调用
addText()上千次；改用addListItem()或批量构造TextRun对象 - 图片路径必须是服务器可读的绝对路径（如
/var/www/images/logo.png），相对路径容易因工作目录变化而失败 - 表格列宽单位是
Twips（1/20 磅），不是像素，addCell(1000)≈ 50 磅，别瞎填 10000
