使用Maven的jpackage打包Deb时缺失.desktop文件与图标问题

1. 核对jpackage核心参数的完整性 #

deb包的桌面快捷方式和图标生成依赖jpackage的Linux专属参数，即便开启了linuxshortcut=true，仍需确保以下配置到位：

• 图标路径：必须指定绝对路径的图标文件（推荐PNG格式），比如用Maven变量写为${project.basedir}/src/main/resources/icons/converter.png，避免相对路径导致jpackage无法识别。
• 资源目录与.desktop模板：需要在resourceDir指定的目录下，放置与应用名称同名的.desktop模板文件（比如你的应用叫converter，模板就叫converter.desktop），模板必须包含必要字段：

  [Desktop Entry]
  Name=Converter
  Comment=文件格式转换工具
  Exec=/opt/converter/bin/converter
  Icon=converter
  Terminal=false
  Type=Application
  Categories=Utility;
  

  缺少这些字段或文件名不匹配，jpackage不会自动生成有效的桌面快捷方式。

2. 修正jpackage-maven-plugin的配置细节 #

com.github.akman的插件参数是驼峰命名，别和命令行的短横线参数搞混，正确配置示例如下：

<plugin>
  <groupId>com.github.akman</groupId>
  <artifactId>jpackage-maven-plugin</artifactId>
  <version>1.6.0</version> <!-- 建议使用最新稳定版 -->
  <executions>
    <execution>
      <id>build-deb</id>
      <phase>package</phase>
      <goals>
        <goal>jpackage</goal>
      </goals>
      <configuration>
        <input>${project.build.directory}/jlink-image</input> <!-- jlink生成的镜像目录 -->
        <dest>${project.build.directory}/packages</dest>
        <name>converter</name>
        <type>deb</type>
        <linuxShortcut>true</linuxShortcut>
        <icon>${project.basedir}/src/main/resources/icons/converter.png</icon>
        <resourceDir>${project.basedir}/src/main/resources/jpackage</resourceDir> <!-- 存放.desktop模板的目录 -->
        <module>你的主模块路径/你的主类全限定名</module>
      </configuration>
    </execution>
  </executions>
</plugin>

重点：插件的linuxShortcut是驼峰写法，别写成小写的linuxshortcut，否则参数不生效。

3. 检查deb包内部的文件结构 #

用dpkg -x converter.deb tmp解压deb包，查看内部是否包含预期文件：

• 图标应在tmp/usr/share/icons/hicolor/[分辨率]/apps/converter.png（比如128x128目录下）
• .desktop文件应在tmp/usr/share/applications/converter.desktop
  如果deb包内部就没有这些文件，说明jpackage未生成，问题出在参数配置；如果内部存在，但安装后看不到快捷方式，是因为jpackage默认把文件放到系统级目录，不是用户的$HOME/.local/share。

4. 区分系统级与用户级路径的差异 #

jpackage生成的deb默认将桌面文件放到/usr/share/applications，图标放到/usr/share/icons，而非用户个人目录。可以通过以下命令验证：

# 检查桌面文件
ls /usr/share/applications/converter.desktop
# 检查图标
ls /usr/share/icons/hicolor/*/apps/converter.png

如果文件存在，运行update-desktop-database刷新桌面缓存，或重启桌面环境即可识别快捷方式。

5. 修正CLI版jpackage的参数格式 #

直接用命令行运行jpackage时，参数是短横线分隔，和Maven插件的驼峰命名不同，正确命令示例：

jpackage --type deb \
  --input ./target/jlink-image \
  --name converter \
  --linux-shortcut true \
  --icon ./src/main/resources/icons/converter.png \
  --resource-dir ./src/main/resources/jpackage \
  --module 你的主模块路径/你的主类全限定名

6. 验证JDK版本兼容性 #

jpackage在JDK 11、17、21等版本上的参数行为有差异，建议使用LTS版本（如JDK17或21），同时确保maven-jlink-plugin和jpackage-maven-plugin的版本与JDK版本匹配。

内容的提问来源于stack exchange，提问作者CraigFoote