Composer安装phpoffice/phpword失败需先确认PHP≥8.0且启用zip、xml扩展；v1.2+类路径为PhpOffice\PhpWord，须正确命名空间并执行dump-autoload；生成.docx需调用save()且避免输出干扰；中文显示需显式设置Microsoft YaHei等字体并确保PHP文件UTF-8无BOM。
Composer 安装 phpoffice/phpword 失败？先确认 PHP 版本和扩展
phpoffice/phpword 最新版（v1.2+）要求 PHP ≥ 8.0，且必须启用 zip 和 xml 扩展。常见错误是执行 composer require phpoffice/phpword 后报 your requirements could not be resolved，本质是版本锁死或扩展缺失。
- 运行
php -v确认 PHP 版本；低于 8.0 请降级安装 v1.1：composer require phpoffice/phpword:^1.1 - 检查
zip是否启用：php -m | grep zip，没输出就需在php.ini中取消;extension=zip的注释 - Windows 用户若用 XAMPP/MAMP，请确保 CLI 使用的
php.ini和 Web 服务器一致，否则扩展可能只在浏览器生效
require phpoffice/phpword 后无法 new \PhpOffice\PhpWord\PhpWord()
自动加载失败最常因命名空间拼错或 Composer 自动加载未刷新。v1.2+ 的类路径已从 PHPWord 改为 PhpOffice\PhpWord，旧教程里的 new PHPWord() 会直接报 Class 'PHPWord' not found。
- 正确实例化写法：
$phpWord = new \PhpOffice\PhpWord\PhpWord(); - 如果用了
use，必须完整写：use PhpOffice\PhpWord\PhpWord;，不能简写成use PHPWord - 执行
composer dump-autoload强制重生成自动加载映射，尤其在手动改过composer.json后
生成 .docx 文件但打开提示“文件已损坏”
根本原因是输出前未关闭写入流，或响应头/缓冲干扰了二进制内容。PHPWord 生成的是内存中的 ZIP 结构，必须调用 save() 并确保无额外输出。
- 保存到文件：用
$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');+$objWriter->save('hello.docx'); - 直接输出浏览器：必须清空输出缓冲、设置正确 header，且不能有任何
echo、var_dump或空白字符在save()前后 - 常见坑：
save('php://output')在某些 Nginx + PHP-FPM 配置下会因 fastcgi_buffering 导致截断，建议先存临时文件再readfile()
用 PhpWord 写中文却显示方块或乱码
不是字体问题，而是 PHPWord 默认不嵌入中文字体，且 .docx 规范要求显式声明字体族。即使系统有微软雅黑，不指定就会回退到不支持中文的默认西文字体。
立即学习“PHP免费学习笔记（深入）”；
- 必须为段落/文本显式设置中文字体：
$section->addText('你好世界', ['name' => 'Microsoft YaHei', 'size' => 14]); - 避免用
'SimSun'（宋体），部分 Office 版本对旧字体兼容差；优先选'Microsoft YaHei'或'Noto Sans CJK SC' - 如果生成后仍乱码，检查 PHP 文件本身编码是否为 UTF-8 无 BOM —— BOM 会被当作文本内容写入 ZIP，破坏结构
