Jersey 版本不匹配導致「The ResourceConfig instance does not contain any root resource classes」錯誤解決

錯誤現象

Tomcat 啟動時報錯：

嚴重: The ResourceConfig instance does not contain any root resource classes.
com.sun.jersey.api.container.ContainerException: The ResourceConfig instance does not contain any root resource classes.
...
Servlet /Servlet_Study_1 threw load() exception

原因分析

此錯誤通常由 Jersey 版本與 web.xml 配置不匹配引起。常見情況：

• Jersey 1.x 與 2.x 配置方式差異巨大（包名、Servlet 類名均不同）。
• web.xml 中 init-param 的 jersey.config.server.provider.packages 掃描路徑錯誤或缺失。
• 依賴包版本衝突（如同時引入 jersey-server 1.x 與 2.x）。

web.xml 關鍵配置對比

Jersey 1.x (舊版)

<servlet>
    <servlet-name>Jersey REST Service</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>com.yourpackage.resource</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

Jersey 2.x / 3.x (新版)

<servlet>
    <servlet-name>Jersey REST Service</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>com.yourpackage.resource</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

解決步驟

1. 確認 Jersey 版本：查看 pom.xml 或 lib 目錄下的 jar 包版本號。
2. 統一 Servlet 類名與參數名：根據版本修改 web.xml 中的 servlet-class 及 init-param 的 param-name。
3. 檢查資源類掃描路徑：確保 param-value 指向的包下存在帶 @Path 註解的資源類。
4. 清理依賴衝突：使用 mvn dependency:tree 排查傳遞性依賴，排除舊版 Jersey 包。

實戰案例

原提問者最終確認：「解決了，是 jersey 版本的問題」。將 web.xml 配置調整為與項目實際引用的 Jersey 版本一致後，錯誤消失。

最佳實踐建議

• 新項目優先選擇 Jersey 2.x+ (或 Jakarta RESTful Web Services 3.0+)。
• 使用 Maven BOM 管理版本：<dependencyManagement> 引入 jersey-bom。
• 啟用 Jersey 的 Application 子類自動掃描，減少 XML 配置。