本文详解 jpackage 在 Windows 平台下设置 $APPDIR 动态类路径（使用分号分隔）及通过 -Djava.library.path 指定本地 DLL 搜索目录的完整实践方法，解决类加载失败与 JNI 库找不到等典型问题。
本文详解 jpackage 在 windows 平台下设置 `$appdir` 动态类路径（使用分号分隔）及通过 `-djava.library.path` 指定本地 dll 搜索目录的完整实践方法，解决类加载失败与 jni 库找不到等典型问题。
在使用 jpackage 打包 Java 应用为 Windows 原生可执行文件（如 .exe 或 .msi）时，若需灵活控制运行时类路径（classpath）或加载本地依赖（如 SQL Server 的 mssql-jdbc 所需的 sqljdbc_auth.dll），直接沿用 Unix 风格命令会导致路径解析失败——这是开发者常遇到的核心痛点。关键在于：Windows 下必须使用分号（;）作为 classpath 分隔符，且 $APPDIR 必须原样保留（不可被 Shell 展开）。
✅ 正确配置自定义类路径（Windows）
jpackage 生成的启动器会在运行时自动将 $APPDIR 替换为实际安装目录（如 C:\Program Files\MyApp）。但若你在 PowerShell 或 CMD 中直接拼接 --java-options，Shell 可能提前解析 $APPDIR（视引号类型而定），导致 CFG 文件中该变量消失，最终 classpath 变成绝对无效路径（如 \config;...\MyApp.jar），进而触发 ClassNotFoundException。
推荐写法（PowerShell）：
使用单引号包裹整个参数值，彻底禁用变量展开：
jpackage --name MyApp ` --input target/app/ ` --main-class "path.to.my.MainClass" ` --main-jar MyApp.jar ` --java-options '-cp $APPDIR\config;$APPDIR\lib\gson-2.10.1.jar;$APPDIR\lib\xmlbeans-5.1.1.jar;$APPDIR\lib\mssql-jdbc-12.4.0.jre8.jar;$APPDIR\MyApp.jar'
✅ 生成的 MyApp.cfg 将包含：
java-options=-cp java-options=$APPDIR\config;$APPDIR\lib\gson-2.10.1.jar;$APPDIR\lib\xmlbeans-5.1.1.jar;$APPDIR\lib\mssql-jdbc-12.4.0.jre8.jar;$APPDIR\MyApp.jar
⚠️ 注意事项：
- 严禁使用双引号（
"）包裹--java-options值（PowerShell/CMD 会尝试展开$APPDIR）；- 确保
config/目录和所有 JAR 文件已放入--input指定的输入目录中（如target/app/config/,target/app/lib/）；- 若使用 Maven 插件（如
jpackage-maven-plugin），需在<options></options>中用"转义双引号，并确保$APPDIR不被 Maven 属性解析器误处理。
✅ 加载本地 DLL：通过 java.library.path 指定搜索目录
SQL Server JDBC 驱动启用 Windows 身份验证（Active Directory）时，依赖 sqljdbc_auth.dll。该 DLL 必须位于 JVM 的本地库搜索路径中。jpackage 支持通过 -Djava.library.path 动态指定路径，且同样支持 $APPDIR：
--java-options '-Djava.library.path=$APPDIR\lib'
然后，将 sqljdbc_auth.dll 放入 --input 目录下的 lib/ 子目录（例如：target/app/lib/sqljdbc_auth.dll）。打包后，应用启动时即可通过 System.loadLibrary("sqljdbc_auth") 成功加载。
? 进阶建议：
- 可合并多个
--java-options，例如同时设置 classpath 和 library path：--java-options '-cp $APPDIR\config;...;$APPDIR\MyApp.jar' ` --java-options '-Djava.library.path=$APPDIR\lib'
- 验证 DLL 加载：在主类中添加调试代码：
System.out.println("java.library.path = " + System.getProperty("java.library.path")); System.loadLibrary("sqljdbc_auth"); // 显式触发加载，便于快速定位错误
总结
jpackage 的 $APPDIR 是平台无关的运行时占位符，但其使用方式高度依赖宿主 Shell 的语义。在 Windows 上：
? 类路径分隔符必须为 ;（非 :）；
? $APPDIR 必须用单引号保护，避免提前展开；
? java.library.path 是管理本地 DLL 的标准、可靠机制，无需修改系统 PATH 环境变量；
? 所有资源（JAR、配置、DLL）均应组织在 --input 目录内，保持相对路径结构清晰。
遵循上述规范，即可构建出开箱即用、路径鲁棒、符合企业部署要求的 Windows Java 应用安装包。
