如何解决JavaFX模块化项目JLink打包后MySQL JDBC驱动缺失问题

DevOps 小满

2026-7-17

解决方案

问题根因

jlink 仅会打包模块化JAR或自动模块，且只包含--add-modules指定模块及其依赖链内的模块。你的MySQL驱动要么未被项目模块声明依赖，要么未被jlink纳入打包范围，导致运行时无法找到JDBC驱动。

步骤1：修改`module-info.java`声明MySQL驱动依赖

根据你使用的MySQL Connector/J版本，添加对应依赖语句：

8.0.23及以上版本（模块化驱动）：驱动自带module-info.java，模块名为com.mysql.cj.jdbc，需在模块声明中添加：

module projectTMIP {
    // 保留原有依赖
    requires javafx.controls;
    requires java.sql;
    requires javafx.fxml;
    requires javafx.graphics;
    requires transitive javafx.base;

    // 添加MySQL驱动依赖
    requires com.mysql.cj.jdbc;

    opens model to javafx.graphics, javafx.fxml;
    opens controller to javafx.fxml;
    exports controller;
}

8.0.23以下版本（非模块化驱动）：驱动无module-info.java，会被识别为自动模块，模块名由JAR文件名推导（通常为mysql.connector.java），需添加：
```
module projectTMIP {
    // 保留原有依赖...

    // 添加自动模块依赖
    requires mysql.connector.java;
}
```

步骤2：调整jlink命令，确保驱动被纳入打包

在--add-modules中显式包含MySQL驱动模块，同时确认--module-path正确指向驱动JAR：

# 模块化驱动版本示例（Windows环境）
jlink --module-path "path/to/jmod";"path/to/mysql-connector-java-xxx.jar";bin --add-modules projectTMIP,com.mysql.cj.jdbc --output output/image --launcher run=projectTMIP/model.Main

# 非模块化驱动版本示例（Windows环境）
jlink --module-path "path/to/jmod";"path/to/mysql-connector-java-xxx.jar";bin --add-modules projectTMIP,mysql.connector.java --output output/image --launcher run=projectTMIP/model.Main