Spring Boot Fat Jar 构建与运行失败的完整排查与修复指南-java教程-PHP中文网

Spring Boot Fat Jar 构建与运行失败的完整排查与修复指南

本文详解 Spring Boot 项目因错误使用 ./gradlew jar 导致 Fat Jar 缺失依赖、启动报“Failed to determine a suitable driver class”等典型错误的根本原因，并提供标准化构建流程、配置修正及验证方法，确保生成真正可执行的内嵌依赖 Fat Jar。

本文详解 spring boot 项目因错误使用 `./gradlew jar` 导致 fat jar 缺失依赖、启动报“failed to determine a suitable driver class”等典型错误的根本原因，并提供标准化构建流程、配置修正及验证方法，确保生成真正可执行的内嵌依赖 fat jar。

在 Spring Boot 项目中，“能本地运行 ≠ 能直接部署”——这是许多开发者踩坑的起点。你遇到的 Failed to determine a suitable driver class 错误（源自 DataSourceConfiguration$Hikari），表面是数据库驱动未识别，实则是 Fat Jar 未正确打包 mysql-connector-j 运行时依赖 所致。根本原因在于：你执行了 ./gradlew jar，而非 Spring Boot 官方推荐的构建命令。

? 错误根源：`jar` 任务 ≠ `bootJar` 任务

Gradle 中存在两个关键 JAR 构建任务：

jar：Gradle 原生任务，仅打包本模块编译的 .class 和资源文件，完全忽略依赖（即使你手动配置了 from(configurations.runtimeClasspath)，也因执行时机与类路径解析逻辑问题，极易失效或不兼容 Spring Boot 的嵌套结构）；
bootJar：Spring Boot Gradle Plugin 提供的专用任务，自动执行 repackage 逻辑——它会：
- 将 BOOT-INF/classes/（你的代码）和 BOOT-INF/lib/（所有 runtime 依赖，含 mysql-connector-j）按 Fat Jar 规范组织；
- 注入 org.springframework.boot.loader.JarLauncher 作为主类；
- 生成符合 java -jar 启动协议的 MANIFEST.MF（含 Main-Class: org.springframework.boot.loader.JarLauncher 和 Start-Class: com.example.test.TestApplicationKt）。

而你的 build.gradle.kts 中自定义的 tasks.withType<jar></jar> 块，不仅冗余，更会干扰 bootJar 的正常行为，且 runtimeOnly("com.mysql:mysql-connector-j") 在 jar 任务中根本不会被包含（runtimeClasspath 在 jar 阶段未正确解析）。

✅ 正确构建 Fat Jar 的标准步骤

1. 删除自定义 `jar` 配置（关键！）

移除 build.gradle.kts 中全部 tasks.withType<jar></jar> 块。Spring Boot Gradle Plugin 已为你封装了完备逻辑，无需手动干预。

2. 确保插件正确启用

确认已应用 Spring Boot 插件（你已配置 id("org.springframework.boot")），并显式启用 bootJar 任务（Gradle 7+ 默认启用，但建议显式声明）：

Spring Boot 3.3.13

Spring Boot下载页提供 3.3.13 官方源码 ZIP，并整理快速入门、项目创建、配置和自动配置说明。

下载

// build.gradle.kts
plugins {
    id("org.springframework.boot") version "3.1.1" // ✅ 已正确声明
    id("io.spring.dependency-management") version "1.1.0"
    kotlin("jvm") version "1.8.22"
    kotlin("plugin.spring") version "1.8.22"
    kotlin("plugin.jpa") version "1.8.22"
}

// ✅ 确保 bootJar 任务启用（Gradle 7+ 可省略，但显式更清晰）
tasks.named<org.springframework.boot.gradle.tasks.bundling.bootjar>("bootJar") {
    archiveClassifier.set("") // 生成无 classifier 的主 jar（如 app.jar 而非 app-boot.jar）
}</org.springframework.boot.gradle.tasks.bundling.bootjar>

3. 使用正确的构建命令

# ❌ 错误：跳过 Spring Boot 生命周期，仅执行原生 jar 任务
./gradlew jar

# ✅ 正确：触发完整构建生命周期，自动生成 Fat Jar
./gradlew clean bootJar
# 或（等价于 bootJar，因 bootJar 是 package 阶段默认任务）
./gradlew clean build

生成的 Fat Jar 默认位于 build/libs/your-app-0.0.1-SNAPSHOT.jar。

4. 验证 Fat Jar 是否合规

执行以下命令验证：

# 检查是否为 Spring Boot Fat Jar（应输出 jarmode 支持信息）
java -Djarmode=help -jar build/libs/your-app-0.0.1-SNAPSHOT.jar

# 检查 BOOT-INF 结构是否存在
jar -tf build/libs/your-app-0.0.1-SNAPSHOT.jar | grep -E "^(BOOT-INF|META-INF/MANIFEST)"
# ✅ 正常输出应包含：BOOT-INF/classes/, BOOT-INF/lib/mysql-connector-j-8.x.x.jar, META-INF/MANIFEST.MF

# 检查 MANIFEST 中主类（应为 JarLauncher）
unzip -p build/libs/your-app-0.0.1-SNAPSHOT.jar META-INF/MANIFEST.MF | grep -E "(Main-Class|Start-Class)"
# ✅ 输出示例：
# Main-Class: org.springframework.boot.loader.JarLauncher
# Start-Class: com.example.test.TestApplicationKt

⚠️ 补充注意事项

runtimeOnly 依赖必须被 bootJar 捕获：mysql-connector-j 已正确声明为 runtimeOnly，bootJar 会自动将其打包进 BOOT-INF/lib/；若仍缺失，请检查 ./gradlew dependencies --configuration runtimeClasspath 是否列出该依赖。
避免 IDE “导出 JAR” 功能：VS Code/IntelliJ 的 Export 向导生成的是普通 JAR，永远不要用它替代 bootJar。
Linux 部署前检查：确保目标服务器安装 JDK 17+（匹配 sourceCompatibility），且 MySQL 服务可达、端口开放。

调试启动失败：添加 JVM 参数获取详细日志：

java -Dlogging.level.org.springframework=DEBUG -Dlogging.level.com.zaxxer.hikari=DEBUG -jar build/libs/your-app-0.0.1-SNAPSHOT.jar

✅ 总结：一句话原则

Spring Boot 项目必须使用 ./gradlew bootJar（或 ./gradlew build）生成 Fat Jar；任何绕过 bootJar 的构建方式（如 jar、assemble、IDE 导出）均会导致依赖缺失、类加载失败，进而引发 ClassNotFoundException、UnsatisfiedDependencyException 或 Failed to determine driver class 等典型错误。

遵循此规范，你的 Fat Jar 将完整携带 mysql-connector-j 及所有依赖，java -jar 启动后即可成功连接数据库并正常运行。