PHP DOMDocument 处理外部实体的安全边界

PHP DOMDocument 处理不可信 XML 时，安全边界不在某一个“万能开关”，而在于同时控制外部实体加载、实体替换和网络访问。默认导入场景应关闭外部解析；只有确实需要 DTD 或内部实体时，才在明确的版本与输入范围内开启最小能力。

官方手册：https://www.php.net/manual/en/class.domdocument.php

实用结论：让 resolveExternals 与 substituteEntities 保持关闭，解析选项加入 LIBXML_NONET，支持时再加入 LIBXML_NO_XXE；如果业务仍可能触发外部实体回调，再用 libxml_set_external_entity_loader() 返回 null 做最后一道拒绝边界。

先把三个实体开关分开看

DOMDocument::$resolveExternals 控制是否从 DOCTYPE 声明中加载外部实体；DOMDocument::$substituteEntities 控制实体是否替换进文档树，这两个属性的默认值都是偏保守的。真正容易造成误判的是 LIBXML_NOENT：它的名字像是“不要实体”，实际含义是开启实体替换，官方手册明确提醒这可能放大 XXE 风险。

LIBXML_NONET 负责禁止加载文档时的网络访问，但它不是“所有外部实体都安全”的同义词；文件系统、DTD 校验和实体替换仍需单独审查。PHP 8.4.0 起，在 libxml 至少为 2.13.0 的环境里可以使用 LIBXML_NO_XXE，它专门用于实体替换过程中的 XXE 阻断。

建立一个默认拒绝外部实体的解析入口

把安全策略集中到一个函数里，比在每个控制器里临时拼选项更容易审查。下面的入口针对上传 XML 或第三方接口响应：普通元素照常解析，外部实体加载器不提供任何流，网络访问保持关闭；如果运行环境提供 LIBXML_NO_XXE，就把它加入位掩码。

resolveExternals = false;
    $document->substituteEntities = false;

    // 让调用方得到可处理的布尔结果，而不是把警告直接输出到响应。
    libxml_use_internal_errors(true);
    try {
        if (!$document->loadXML($xml, $options)) {
            throw new InvalidArgumentException('XML 解析失败');
        }
        return $document;
    } finally {
        // 清理本次解析产生的错误，避免污染后续请求的诊断信息。
        libxml_clear_errors();
        libxml_use_internal_errors(false);
    }
}

这个函数的重点不是把 XML 解析成“绝对不能失败”，而是把失败控制在预期边界内。外部实体被拒绝后，业务层应把它当作输入不符合策略，而不是自动重试、改用 LIBXML_NOENT 或放宽网络权限。

需要 DTD 时，先缩小能力再决定是否替换实体

有些旧 XML 格式依赖 DTD 中的内部字符实体，但这不等于必须允许任意外部实体。可以把需求拆开：只读取普通元素时不使用 LIBXML_NOENT；需要内部实体替换时，先确认运行环境有 LIBXML_NO_XXE，同时保留 LIBXML_NONET 和拒绝式外部实体加载器。

不要把 DOMDocument::$validateOnParse、LIBXML_DTDVALID 或 LIBXML_DTDLOAD 当作格式“修复器”。它们会改变 DTD 读取与校验范围，官方文档同样提醒 DTD 校验可能促进 XXE 风险。LIBXML_PARSEHUGE 也只应在可信输入和明确资源上限下使用，因为它会提高解析器的硬编码限制。

兼容旧环境时，不要依赖已弃用的全局开关

libxml_disable_entity_loader() 从 PHP 8.0 起已弃用，原因是外部实体加载默认已经被禁用；它还是一个全局状态开关，容易让同一进程中的其它 XML 代码互相影响。新代码优先使用解析选项和 libxml_set_external_entity_loader()，并把策略放在可复用的入口中。

如果项目需要支持旧 PHP 或旧 libxml，不能假设 LIBXML_NO_XXE 一定存在。用 defined() 做能力探测只是兼容处理，不能替代外部实体加载器的拒绝策略，也不能因此把 LIBXML_NOENT 无条件打开。

上线前固定四项检查

• 输入来源是否不可信：上传、Webhook、第三方响应都按不可信处理。
• 是否显式关闭 resolveExternals、substituteEntities，并加入 LIBXML_NONET。
• 是否在支持时加入 LIBXML_NO_XXE，并让外部实体加载器返回 null。
• 是否把解析失败、DTD 需求和错误日志分开处理，没有用放宽选项掩盖输入问题。

把这四项写进代码评审模板，通常比记忆某个版本的单一配置更稳妥。安全边界应跟着输入来源和业务所需 XML 能力变化，而不是跟着一段历史博客的固定写法变化。

常见问题

LIBXML_NONET 是否已经完全解决 XXE？

没有。它主要禁止网络访问，实体替换、DTD 校验、文件系统来源和外部实体回调仍要分别控制。

为什么不直接把 LIBXML_NOENT 去掉就结束？

对普通 XML 导入，去掉它通常是正确起点；但还要明确对象属性、网络选项和外部实体加载器，避免其它调用路径重新打开解析能力。

PHP 8.4 的 LIBXML_NO_XXE 能否替代全部兼容代码？

不能。它依赖 libxml 版本，并且项目可能仍运行在旧 PHP 或旧系统库上。用能力探测兼容新环境，同时保留拒绝式加载器和最小权限原则。