Gradle构建Spring Boot Jar包部署Linux服务器启动失败：无自动配置类

我之前在部署Spring Boot项目到Linux服务器时也遇到过几乎一模一样的报错，核心问题都是Jar包没有被正确打包成Spring Boot可执行Jar，导致服务器启动时找不到自动配置类。下面是我总结的排查和解决步骤：

1. 检查Gradle构建配置是否正确 #

Spring Boot项目必须依赖spring-boot-gradle-plugin才能生成包含自动配置和依赖的可执行Jar，首先确认你的build.gradle（或build.gradle.kts）里有正确的插件配置：

// build.gradle 示例配置
plugins {
    id 'org.springframework.boot' version '2.7.14' // 替换成你的Spring Boot版本
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'java'
}

group = 'haughton'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '11' // 替换成你的JDK版本
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // 其他依赖...
}

关键是要确保org.springframework.boot插件被正确应用，它会自动帮你处理可执行Jar的打包逻辑。

2. 用正确的Gradle任务构建Jar包 #

很多人会犯的错误是用普通的jar任务构建，而不是Spring Boot提供的bootJar任务：

• 错误命令：./gradlew jar → 生成的是普通Jar，不包含Spring Boot启动器和自动配置依赖
• 正确命令：./gradlew bootJar → 生成的是可执行Jar，包含所有必要的内容

构建完成后，Jar包会在build/libs/目录下，文件名通常是{项目名}-{版本}.jar。

3. 验证Jar包结构是否正确 #

你可以在本地用命令查看Jar包的结构，确认是否包含Spring Boot所需的目录：

jar tf your-app.jar

正常的Spring Boot可执行Jar应该包含：

• BOOT-INF/classes/：存放你的项目编译后的类文件
• BOOT-INF/lib/：存放所有依赖Jar包
• META-INF/spring-autoconfigure-metadata.properties：自动配置的元数据文件

如果这些内容缺失，说明打包过程有问题。

4. 服务器上用正确的命令启动Jar #

确保在Linux服务器上用java -jar命令启动，而不是手动指定类路径：

java -jar your-app.jar

如果用java -cp your-app.jar haughton.icecreamapi.IcecreamapiApplication这种方式启动，可能会因为类路径不全导致找不到自动配置类。

5. 排查配置类的注解问题 #

如果上面的步骤都没问题，再检查你的AppConfig类：

• 确认它被@SpringBootApplication注解标记（这个注解包含了@ComponentScan、@EnableAutoConfiguration和@Configuration）
• 如果手动使用了@Import注解，检查导入的类是否存在，有没有拼写错误
• 确认@ComponentScan的扫描路径包含了你的项目包（默认是@SpringBootApplication所在包及其子包）

按照上面的步骤排查后，重新构建并部署Jar包，应该就能正常启动了。

内容的提问来源于stack exchange，提问作者Daniel Haughton