执行mvn javadoc:javadoc时无法生成Javadoc压缩包的原因咨询

问题描述 #

我原本通过maven-assembly-plugin执行mvn install操作时，可生成包含Javadoc的ZIP包，但将该execution配置复制到maven-javadoc-plugin后，执行mvn javadoc:javadoc却无法生成对应ZIP包，想询问该现象的原因。

原maven-assembly-plugin配置 #

<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <executions>
    <execution>
      <id>docs-assembly</id>
      <phase>package</phase>
      <configuration>
        <finalName>${project.build.finalName}-${project.version}-Javadoc</finalName>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/main/assemble.xml</descriptor>
        </descriptors>
      </configuration>
      <goals>
        <goal>single</goal>
      </goals>
    </execution>
  </executions>
</plugin>

修改后的maven-javadoc-plugin配置 #

<plugin>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.2.0</version>
  <executions>
    <execution>
      <id>docs-assembly</id>
      <phase>package</phase>
      <configuration>
        <finalName>${project.build.finalName}-${project.version}-Javadoc</finalName>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/main/assemble.xml</descriptor>
        </descriptors>
      </configuration>
      <goals>
        <goal>single</goal>
      </goals>
    </execution>
  </executions>
</plugin>

原因分析 #

• 插件核心功能完全不匹配：maven-assembly-plugin是专门的文件组装打包工具，它的single目标就是根据assemble.xml描述符，将指定文件（比如已生成的Javadoc）打包成ZIP等格式；而maven-javadoc-plugin的核心职责是生成Javadoc文档，它根本没有处理文件组装打包的能力，你配置的<descriptors>、<appendAssemblyId>等参数对它来说是无效的未知配置项，不会被执行。

• 插件目标的含义完全不同：maven-assembly-plugin的single目标代表执行一次打包组装操作，但maven-javadoc-plugin的single目标（等同于javadoc目标）只是用来生成Javadoc文档，和打包操作没有任何关系。把assembly的配置硬套到javadoc插件上，相当于用错了工具的功能。

• 执行触发逻辑不匹配：原配置中maven-assembly-plugin的execution绑定在package阶段，执行mvn install时会依次触发package及后续阶段，从而执行打包；而你修改后虽然把execution绑定在package阶段，但执行的是mvn javadoc:javadoc——这个命令只会单独触发javadoc插件的javadoc目标，不会触发绑定在package阶段的execution，就算触发了，javadoc插件也无法处理打包配置。

正确做法 #

如果需要生成自定义结构的Javadoc ZIP包，正确的方式是保留maven-assembly-plugin的配置，同时确保maven-javadoc-plugin已正确生成Javadoc文件，让assembly插件负责将这些Javadoc文件打包成ZIP。如果只需要标准的Javadoc JAR包，可以直接使用maven-javadoc-plugin的jar目标，无需依赖assembly插件。

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