如何解决OS X 14.3系统中Java 17的jpackage工具遗漏Harfbuzz外部依赖的问题

我之前在OS X 14.3上用Java 17的jpackage制作独立DMG安装包时，刚好踩过这个Harfbuzz依赖遗漏的大坑，先给你拆解清楚问题根源，再分享几个亲测可行的解决办法。

问题到底出在哪？ #

用Homebrew安装的OpenJDK 17会自动带上Harfbuzz文本整形库，这是因为Java核心的libfontmanager.dylib库依赖它来处理字体渲染。你可以用otool命令验证这个依赖关系：

otool -L libexec/openjdk.jdk/Contents/Home/lib/libfontmanager.dylib

执行后会看到类似这样的输出：

libexec/openjdk.jdk/Contents/Home/lib/libfontmanager.dylib:
    /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/lib/libfontmanager.dylib (compatibility version 1.0.0, current version 1.0.0)
    @loader_path/../../../../../../../../opt/harfbuzz/lib/libharfbuzz.0.dylib (compatibility version 60811.0.0, current version 60811.0.0)

本地开发运行的时候这完全没问题——毕竟你的系统上已经通过Homebrew装了这些依赖，但一旦用jpackage打包成独立DMG，麻烦就来了：jpackage默认不会自动识别并打包这种外部系统依赖，导致没装过Java 17的机器上运行这个DMG里的程序直接启动失败。

更麻烦的是，Harfbuzz本身还依赖其他不在标准Java 17安装包内的库，比如Freetype。你同样可以用otool查看：

otool -L libharfbuzz.0.dylib

输出里会看到类似这样的依赖项：

...
    /opt/homebrew/opt/freetype/lib/libfreetype.6.dylib (compatibility version 27.0.0, current version ...

可行的解决办法 #

1. 换用官方JDK 17（最省心的方案）

如果你不想手动折腾依赖，最简单的办法就是放弃Homebrew安装的JDK，改用官方发布的JDK 17安装包（比如Adoptium、Oracle的DMG版本）。官方JDK会把字体处理相关的必要依赖（包括Harfbuzz的核心部分）内置在JDK包内，完全不依赖系统层面的外部库，这样jpackage打包时就能自动把这些依赖包含进DMG里，不会再出现启动失败的问题。

2. 手动复制依赖并调整路径（适合必须用Homebrew JDK的场景）

如果因为某些原因必须用Homebrew的JDK，那就得手动处理依赖：

• 先用brew --prefix harfbuzz和brew --prefix freetype命令找到Harfbuzz和它依赖的Freetype等库的安装路径；
• 把找到的所有.dylib文件复制到jpackage生成的App Bundle的Contents/Frameworks目录下；
• 用install_name_tool命令修改这些库以及Java的libfontmanager.dylib中的依赖路径，把原来的绝对路径（比如/opt/homebrew/opt/harfbuzz/lib/libharfbuzz.0.dylib）改成App Bundle内部的相对路径，比如@executable_path/../Frameworks/libharfbuzz.0.dylib，确保程序启动时能找到内部的依赖库。

3. 用jlink预构建自定义JRE（进阶方案）

如果你对Java模块系统比较熟悉，可以先用jlink构建一个包含所有必要模块的自定义JRE，在构建时通过--add-modules参数确保字体处理相关的模块被正确包含，再用这个自定义JRE作为jpackage的输入。不过这个方法需要你仔细排查所有依赖的模块，相对麻烦一些。

备注：内容来源于stack exchange，提问作者Buzz Moschetti