Minecraft Forge与SpringBoot共存时NoClassDefFoundError问题求助

问题 #

在同一代码库中运行SpringBoot应用与Minecraft Forge模组（1.12.2版本+ForgeGradle 2.3），Intellij本地运行正常，但将shadowJar生成的fatJar放到服务器mods文件夹时，抛出如下错误：

[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1052]: java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1052]:   at org.springframework.boot.SpringApplication.<clinit>(SpringApplication.java:178)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1052]:   at net.mahmutkocas.mkutils.server.web.WebApplication.lambda$start$0(WebApplication.java:46)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1052]:   at java.lang.Thread.run(Thread.java:750)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]: Caused by: java.lang.ClassNotFoundException: org.apache.commons.logging.LogFactory
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at java.net.URLClassLoader.findClass(URLClassLoader.java:387)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:355)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at net.minecraft.launchwrapper.LaunchClassLoader.findClass(LaunchClassLoader.java:106)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
[21:56:23] [SpringWeb/INFO] [STDERR]: [java.lang.ThreadGroup:uncaughtException:1061]:   ... 3 more

检查发现fatJar中已包含commons-logging依赖，尝试过以下方法均无效：

• 升级到ForgeGradle 3.+；
• 将commons-logging库放在服务器文件夹与jar同级；
• 复制commons-logging代码到项目并保持包名一致；
• 自定义类加载器强制加载jar中类；
• 添加log4j2.xml配置让Spring使用Log4j2；
• 显式移除commons-logging包；
• 添加本地libs目录依赖并放入commons-logging jar。

当前build.gradle内容：

buildscript {
    repositories {
        jcenter()
        maven { url = "https://files.minecraftforge.net/maven" }
    }
    dependencies {
        classpath 'net.minecraftforge.gradle:ForgeGradle:2.3-SNAPSHOT'
    }
}

plugins {
    id 'java'
    id "com.github.johnrengelman.shadow" version "1.2.3"
}
apply plugin: 'net.minecraftforge.gradle.forge'

//Only edit below this line, the above code adds and enables the necessary things for Forge to be setup.


version = '0.0.1'
group = 'net.mahmutkocas'
archivesBaseName = 'mkutils'


configurations.all {
    exclude group: "org.springframework.boot", module:"spring-boot-starter-logging" // Conflicts with forge.
//    exclude group: 'org.springframework', module: 'spring-jcl' // For removing the commons-logging
//    exclude group: 'commons-logging', module: 'commons-logging' // For removing the commons-logging
}

sourceCompatibility = targetCompatibility = '1.8' // Need this here so eclipse task generates correctly.
compileJava {
    sourceCompatibility = targetCompatibility = '1.8'
}

minecraft {
    version = "1.12.2-14.23.5.2838"
    runDir = "run"
    mappings = "snapshot_20171003"
}

dependencies {
    compile group: 'org.springframework.boot', name: 'spring-boot-starter-parent', version: '3.1.2'
    compile 'org.springframework.boot:spring-boot-starter-data-jpa:2.7.14'
    compile 'org.springframework.boot:spring-boot-starter-web:2.7.14'
    compile group: 'io.github.openfeign', name: 'feign-jackson', version: '9.3.1'
    compileOnly 'org.projectlombok:lombok:1.18.28'
    compile 'com.h2database:h2:2.1.214'
    annotationProcessor 'org.projectlombok:lombok:1.18.28'
}

processResources {
    // this will ensure that this task is redone when the versions change.
    inputs.property "version", project.version
    inputs.property "mcversion", project.minecraft.version

    // replace stuff in mcmod.info, nothing else
    from(sourceSets.main.resources.srcDirs) {
        include 'mcmod.info'

        // replace version and mcversion
        expand 'version':project.version, 'mcversion':project.minecraft.version
    }

    // copy everything else except the mcmod.info
    from(sourceSets.main.resources.srcDirs) {
        exclude 'mcmod.info'
    }
}

解决方案 #

核心原因 #

Minecraft Forge的LaunchClassLoader对第三方包有加载限制，同时Spring默认的日志依赖与Forge的Log4j2环境冲突，导致commons-logging类无法被正确加载。

具体修复步骤 #

1. 统一日志依赖，彻底移除commons-logging
   修改configurations.all和dependencies配置，强制Spring使用Log4j2（与Forge日志环境对齐），并排除所有commons-logging相关依赖：

   configurations.all {
       exclude group: "org.springframework.boot", module:"spring-boot-starter-logging"
       exclude group: 'commons-logging', module: 'commons-logging'
       exclude group: 'org.springframework', module: 'spring-jcl'
   }
   
   dependencies {
       // 替换为Log4j2启动器
       compile 'org.springframework.boot:spring-boot-starter-log4j2:2.7.14'
       compile 'org.springframework.boot:spring-boot-starter-data-jpa:2.7.14'
       compile 'org.springframework.boot:spring-boot-starter-web:2.7.14'
       compile group: 'io.github.openfeign', name: 'feign-jackson', version: '9.3.1'
       compileOnly 'org.projectlombok:lombok:1.18.28'
       compile 'com.h2database:h2:2.1.214'
       annotationProcessor 'org.projectlombok:lombok:1.18.28'
       // 添加适配Log4j2的spring-jcl版本（与Spring Boot 2.7.x匹配）
       compile 'org.springframework:spring-jcl:5.3.29'
   }
   

2. 配置ShadowJar处理类加载冲突
   添加ShadowJar配置，重命名第三方依赖包路径，避免与Forge或其他模组的类加载冲突：

   shadowJar {
       mergeServiceFiles()
       // 重命名Spring和日志相关包，让Forge类加载器能识别
       relocate 'org.apache.commons.logging', 'net.mahmutkocas.mkutils.shaded.commons.logging'
       relocate 'org.springframework', 'net.mahmutkocas.mkutils.shaded.springframework'
   }
   
   // 让Forge构建任务依赖shadowJar
   build.dependsOn shadowJar
   

3. 修改Spring启动代码，使用Forge类加载器
   在启动Spring应用时，手动指定上下文类加载器为Forge的LaunchClassLoader：

   public static void start() {
       Thread.currentThread().setContextClassLoader(WebApplication.class.getClassLoader());
       SpringApplication.run(WebApplication.class);
   }
   

4. 验证Jar包内容
   生成Jar后解压检查，确认net.mahmutkocas.mkutils.shaded.commons.logging和net.mahmutkocas.mkutils.shaded.springframework目录存在，依赖已被正确重命名打包。

内容的提问来源于stack exchange，提问作者Doctor One