本文详解 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+ 默认启用，但建议显式声明）：
// 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）
}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 启动后即可成功连接数据库并正常运行。
