解决 PHPWord 中 UTF-8 编码导致的 XML 格式异常问题-php教程-PHP中文网

解决 PHPWord 中 UTF-8 编码导致的 XML 格式异常问题

本文详解 phpword 在处理 draftjs 导出的 utf-8 json 内容时，因重复编码或未正确转义引发的 xml 格式损坏问题，并提供安全的字符处理方案与实践建议。

本文详解 php word 在处理 draftjs 导出的 utf-8 json 内容时，因重复编码或未正确转义引发的 xml 格式损坏问题，并提供安全的字符处理方案与实践建议。

在使用 DraftJS 与 PHPWord 构建动态 Word 文档（如医疗记录、法律文书）的流程中，一个常见但隐蔽的问题是：生成的 .docx 文件打开后内容错乱、样式丢失，甚至无法解析——根源往往并非逻辑错误，而是 UTF-8 字符在多层处理中被意外重复编码或未适配 OpenXML 规范。

你提供的 generate.php 代码中，核心问题出现在字符串预处理环节：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

xmlEntities() 函数被用于转义文本（如 , &），但它若作用于已为 UTF-8 编码的 Unicode 字符串（如中文、特殊符号），可能破坏 XML 声明的编码一致性；
同时，mb_substr()、mb_strlen() 等多字节函数虽保障了中文截取正确性，但若后续又调用 htmlspecialchars() 或手动拼接 XML 片段，极易触发双重编码（例如中文 → 中文 → 中文），最终导致 document.xml 解析失败。

✅ 正确做法：全程信任 UTF-8，仅对 XML 特殊字符做最小化转义
PHPWord 内部默认以 UTF-8 处理内容，因此无需对中文等 Unicode 字符进行 htmlentities() 或 xmlEntities() 编码。只需确保以下三点：

禁用冗余转义
删除所有对纯文本内容调用 xmlEntities() 的逻辑（如代码中 $retext = xmlEntities($p);）。PHPWord 的 addText() 方法会自动处理 XML 安全性：
```
// ❌ 错误：强制转义 Unicode 字符
$textrun->addText(xmlEntities($p), $styles[$l]);

// ✅ 正确：直接传入原始 UTF-8 字符串
$textrun->addText($p, $styles[$l]);
```

显式声明文档编码
在初始化 PHPWord 时，强制设置 UTF-8 输出（尽管新版已默认启用，但仍建议显式声明）：

\PhpOffice\PhpWord\Settings::setOutputEscapingEnabled(true);
\PhpOffice\PhpWord\Settings::setInputEncoding('UTF-8');
$phpWord = new \PhpOffice\PhpWord\PhpWord();

验证 JSON 输入的编码完整性
DraftJS 导出的 JSON 必须为合法 UTF-8。在 json_decode() 前增加校验：

$jsonString = $result['snapshot'];
if (!mb_check_encoding($jsonString, 'UTF-8')) {
    throw new InvalidArgumentException('Invalid UTF-8 encoding in DraftJS snapshot');
}
$decoded = json_decode($jsonString, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    throw new RuntimeException('Invalid JSON: ' . json_last_error_msg());
}

⚠️ 特别注意合并模板时的 XML 操作
你在 ZIP 层直接操作 document.xml，此时 DOMDocument 的加载必须指定编码：

// ✅ 强制以 UTF-8 加载 XML，避免 DOM 自动检测失败
$targetDom = new DOMDocument('1.0', 'UTF-8');
$targetDom->loadXML($targetDocument, LIBXML_NOENT | LIBXML_NOWARNING);

// 同样处理 sourceDocument
$sourceDom = new DOMDocument('1.0', 'UTF-8');
$sourceDom->loadXML($sourceDocument, LIBXML_NOENT | LIBXML_NOWARNING);

? 总结关键原则：