升级WildFly至27.0.1后Docker部署Java应用报NoClassDefFoundError排查

1. 确认Eclipselink版本适配 #

WildFly 14基于Java EE 8，27则是Jakarta EE 10，API包名从javax.persistence全面切换为jakarta.persistence，必须使用支持Jakarta EE 10的Eclipselink版本（至少3.0.x，推荐3.1+）。旧版本Eclipselink不兼容新API，会直接导致找不到持久化提供者。

2. 修正persistence.xml的核心配置 #

检查你的persistence.xml：

• 根元素命名空间需从Java EE的http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd替换为Jakarta EE的https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd
• 持久化提供者类要指定为org.eclipse.persistence.jpa.PersistenceProvider，不要使用旧的javax相关路径

3. 在Docker镜像中配置Eclipselink模块 #

WildFly默认不内置Eclipselink，你本地环境应该已经手动添加了模块，但Docker镜像里的WildFly是干净的，需要在构建镜像时补上：

1. 将Eclipselink jar和对应的jakarta.persistence-api jar复制到WildFly的modules/system/layers/base/org/eclipse/persistence/main目录
2. 在同目录创建module.xml，内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<module name="org.eclipse.persistence" xmlns="urn:jboss:module:1.9">
    <resources>
        <resource-root path="eclipselink.jar"/>
        <resource-root path="jakarta.persistence-api-3.0.0.jar"/>
    </resources>
    <dependencies>
        <module name="jakarta.transaction.api"/>
        <module name="jakarta.xml.bind.api"/>
        <module name="javax.validation.api"/>
        <module name="org.antlr"/>
        <module name="org.apache.commons.collections"/>
        <module name="org.jboss.logging"/>
        <module name="javax.api"/>
        <module name="javax.servlet.api" optional="true"/>
    </dependencies>
</module>

3. 在WildFly的standalone.xml中配置JPA子系统，指定Eclipselink作为提供者：

<subsystem xmlns="urn:jboss:domain:jpa:6.0">
    <jpa default-datasource="" default-extended-persistence-inheritance="DEEP">
        <providers>
            <provider name="eclipselink" module="org.eclipse.persistence"/>
        </providers>
        <jpa-defaults>
            <property name="eclipselink.weaving" value="false"/>
        </jpa-defaults>
    </jpa>
</subsystem>

4. 避免类加载冲突 #

检查你的应用包（WAR/EAR）中是否打包了jakarta.persistence-api或Eclipselink的jar包，若有必须删除，让WildFly的模块来提供这些类。也可以通过jboss-deployment-structure.xml明确依赖模块：

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.eclipse.persistence" slot="main"/>
            <module name="jakarta.persistence.api"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

5. 核对数据源配置 #

确认persistence.xml里的数据源JND名称和Docker环境中WildFly配置的完全一致，本地和Docker的数据源名称可能存在差异，找不到数据源也会触发类似的持久化错误。

内容的提问来源于stack exchange，提问作者saham nadeem