dom4j selectSingleNode 報錯 NoClassDefFoundError: JaxenException 根因與解決

使用 dom4j 的 XPath 查詢方法（selectNodes、selectSingleNode、valueOf）時，拋出 java.lang.NoClassDefFoundError: org/jaxen/JaxenException。本文解析錯誤根因、依賴關係與 Maven/Gradle 修正方案。

一、錯誤堆疊分析

java.lang.NoClassDefFoundError: org/jaxen/JaxenException
    at org.dom4j.DocumentFactory.createXPath(DocumentFactory.java:230)
    at org.dom4j.tree.AbstractNode.createXPath(AbstractNode.java:207)
    at org.dom4j.tree.AbstractNode.selectNodes(AbstractNode.java:164)
    ...
Caused by: java.lang.ClassNotFoundException: org.jaxen.JaxenException

關鍵點：DocumentFactory.createXPath() 內部實例化 Jaxen XPath 引擎，屬於 dom4j 可選依賴，未隨 dom4j 主包傳遞。

二、依賴關係圖譜

dom4j (核心)
   └── 可選依賴 → jaxen (XPath 引擎)
           └── 需顯式引入

• dom4j 1.x/2.x 均將 XPath 實現委託給 Jaxen。
• selectNodes、selectSingleNode、numberValueOf 等方法首次調用時觸發 Class.forName("org.jaxen.XPath")。
• 若 classpath 缺少 jaxen.jar，即拋 NoClassDefFoundError。

三、Maven 修正（推薦）

<dependency>
    <groupId>org.dom4j</groupId>
    <artifactId>dom4j</artifactId>
    <version>2.1.4</version> <!-- 或 1.6.1 -->
</dependency>
<dependency>
    <groupId>jaxen</groupId>
    <artifactId>jaxen</artifactId>
    <version>1.2.0</version> <!-- 必須顯式引入 -->
</dependency>

dom4j 2.x 建議搭配 jaxen 1.2.0+；dom4j 1.x 兼容 jaxen 1.1.6。

四、Gradle 修正

implementation 'org.dom4j:dom4j:2.1.4'
implementation 'jaxen:jaxen:1.2.0'

五、手動 JAR 包部署（非建構工具專案）

1. 下載 jaxen-1.2.0.jar（Maven Central 搜尋）。
2. 放入專案 WEB-INF/lib 或應用伺服器共享庫目錄。
3. 重新部署/重啟應用。

六、常見避坑指南

七、替代方案：原生 DOM + XPath

若不願引入額外依賴，JDK 內建 javax.xml.xpath 可滿足基本需求：

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
Document doc = dbf.newDocumentBuilder().parse(inputStream);
XPathFactory xpf = XPathFactory.newInstance();
XPath xpath = xpf.newXPath();
Node node = (Node) xpath.evaluate("//featureMember", doc, XPathConstants.NODE);
NodeList list = (NodeList) xpath.evaluate("//featureMember", doc, XPathConstants.NODESET);

• 零額外依賴，效能略優於 dom4j+Jaxen。
• API 較繁瑣，不支援 dom4j 的便利方法（element.getStringValue() 等）。

八、總結

• dom4j XPath 功能依賴 Jaxen，屬可選依賴，必須顯式引入。
• Maven/Gradle 專案直接加入 jaxen:jaxen 依賴即可解決。
• 排查類衝突時關注 ClassLoader 優先順序與容器內建庫。