DOMXPath 命名空间怎么配置或排查

DOMXPath 查询 XML 时，最容易误判的一种情况是“节点明明存在，结果却为空”。如果 XML 使用了默认命名空间，XPath 里的 //catalog/item 实际是在查“没有命名空间的元素”，自然匹配不到。稳定的做法是先确认 namespace URI，再用 DOMXPath::registerNamespace() 把 URI 绑定到一个自己选的前缀，最后让 XPath 的每一级目标元素都带上这个前缀。

DOMXPath 查询前，先把 URI 映射成自己的前缀

先看一段带默认命名空间的 XML。这里的 catalog 和 item 都属于 urn:demo:catalog，只是 XML 没有给它写一个显式的 c: 前缀。

不管你是解析带命名空间的RSS、SVG还是自定义XML文档，只要先调用`$domXPath->registerNamespace()`把对应前缀和真实命名空间URI绑定，之后用绑定好的前缀写查询表达式，绝大多数查询失败的问题都能快速定位解决。

蓝色文件夹
XML;

$doc = new DOMDocument();
// loadXML 返回 false 时，先处理输入 XML 的格式问题。
if (!$doc->loadXML($xml)) {
    throw new RuntimeException('XML 载入失败');
}

$root = $doc->documentElement;
$namespaceUri = $root->namespaceURI;
// namespaceURI 是判断 XPath 前缀是否映射正确的第一份证据。
if ($namespaceUri !== 'urn:demo:catalog') {
    throw new RuntimeException('命名空间 URI 与预期不一致');
}

$xpath = new DOMXPath($doc);
// x 只是 XPath 内部的别名，名称可以由业务代码自己决定。
$xpath->registerNamespace('x', $namespaceUri);

// 默认命名空间中的每一级元素都使用 x: 前缀。
$nodes = $xpath->query('//x:catalog/x:item/x:name');
if ($nodes === false) {
    throw new RuntimeException('XPath 表达式或上下文节点无效');
}

foreach ($nodes as $node) {
    echo trim($node->textContent), PHP_EOL;
}

这里不要把 xmlns 后面的 URI 当成可有可无的装饰。XPath 的元素测试包含命名空间语义；XML 的默认命名空间不会自动变成 XPath 的默认命名空间。即使原文档后来把显式前缀从 c:item 改成 p:item，只要 URI 仍然相同，代码里的 x:item 仍然可以工作。

默认命名空间要主动注册，源文档前缀不必照搬

命名空间的好处在于，查询代码可以建立自己的稳定契约。业务代码关心的是“目录元素属于哪个 URI”，而不是供应方今天把它写成 c:、doc: 还是默认命名空间。

如果 XML 同时有两个命名空间，应分别注册，不能因为它们都“看起来像标签”就共用一个 URI：

registerNamespace('c', 'urn:demo:catalog');
$xpath->registerNamespace('m', 'urn:demo:meta');

// c:item 与 m:label 属于不同命名空间，查询中要分别写前缀。
$nodes = $xpath->query('//c:item/m:label');
if ($nodes === false) {
    throw new RuntimeException('多命名空间 XPath 语法或上下文错误');
}

把空结果和 false 分开排查

DOMXPath::query() 返回 false，通常说明 XPath 表达式格式错误或上下文节点无效；返回一个空的 DOMNodeList，则说明表达式可以执行，只是没有找到符合条件的节点。先区分这两种结果，排查方向会少一半。

query('//x:catalog/x:item');

if ($result === false) {
    // 这是执行层错误：检查括号、引号、轴语法和 contextNode。
    throw new RuntimeException('XPath 无法执行');
}

if ($result->length === 0) {
    // 这是匹配层问题：继续核对 URI、前缀和元素层级。
    echo '表达式有效，但当前文档没有匹配节点', PHP_EOL;
} else {
    // 只有命中节点时，才读取 textContent 或属性。
    echo '命中节点数：', $result->length, PHP_EOL;
}

实战中可以按这个顺序复核：

1. 打印或记录根元素的 namespaceURI，确认 URI 没有写错。
2. 确认 registerNamespace() 和 query() 使用的是同一个 DOMXPath 实例。
3. 从短路径开始，例如先查 //x:catalog，再逐级追加 x:item、x:name。
4. 如果结果为 false，先检查 XPath 字符串和 contextNode，不要先改 URI。

什么时候应该把命名空间映射封装起来

一次性脚本可以直接注册前缀；在导入订单、发票或供应链 XML 的服务中，建议把 URI 映射放在一个小函数或配置对象里。这样供应方增加元数据命名空间时，只需更新映射表，业务查询仍然使用稳定的 c:、m: 前缀。

不要用“删除所有命名空间字符串”的方式修复空结果。那会丢掉元素身份信息，两个词面相同但 URI 不同的节点可能被混在一起。正确的判断标准是：URI 映射明确、每一级路径语义清楚、返回值经过区分处理，之后再考虑把查询封装成可复用的查询契约。

相关问题

XPath 前缀必须和 XML 里的前缀一样吗？

不必须。XPath 前缀是当前 DOMXPath 对象里的别名，只要它注册到正确的 namespace URI，就不需要照搬 XML 源文档的前缀。

为什么 //catalog/item 查不到默认命名空间节点？

因为这条表达式表示没有命名空间的元素。默认命名空间也要先注册，例如绑定为 x，再使用 //x:catalog/x:item。

空的 DOMNodeList 是不是 XML 格式错误？

不一定。它更常见地表示表达式执行成功但没有匹配节点；XML 载入失败、XPath 语法错误和上下文无效要分别看载入返回值或 query() 是否为 false。

参考手册：https://www.php.net/manual/en/domxpath.registernamespace.php、https://www.php.net/manual/en/domxpath.query.php。