如何在maven-javadoc-plugin中正确配置类路径？解决自定义Doclet类找不到问题

我之前也碰到过一模一样的情况——自定义Doclet在Eclipse里跑JUnit完全正常，用Maven执行就找不到第三方依赖类，手动加几十个Jar到类路径实在太折腾。下面给你两个便捷的配置方案，不用逐个依赖去写：

方案一：利用javadoc插件内置参数自动引入依赖 #

maven-javadoc-plugin本身就有参数可以自动把项目的编译、运行时依赖全部加入Doclet的类路径，不用手动配置每个Jar。你只需要在插件配置里加上classpathDependencyScope参数：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.5.0</version> <!-- 建议用最新稳定版，避免旧版本bug -->
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <!-- 指定你的自定义Doclet全类名 -->
                <doclet>com.yourpackage.YourCustomDoclet</doclet>
                <!-- 如果你的Doclet是单独的Maven依赖，这里配置它的坐标；如果Doclet在当前项目里，这部分可以删掉 -->
                <docletArtifact>
                    <groupId>com.yourgroup</groupId>
                    <artifactId>your-custom-doclet</artifactId>
                    <version>1.0.0</version>
                </docletArtifact>
                <!-- 关键配置：自动引入项目compile+runtime范围内的所有依赖 -->
                <classpathDependencyScope>compile+runtime</classpathDependencyScope>
                <!-- 要是你的Doclet需要额外参数，在这里加就行 -->
                <!-- <additionalparam>-yourCustomParam someValue</additionalparam> -->
            </configuration>
        </plugin>
    </plugins>
</build>

这个方案最省心，直接利用插件的内置能力帮你搞定类路径，不需要额外的插件步骤。

方案二：用依赖插件生成类路径（更灵活） #

如果方案一因为某些原因不生效（比如旧版本插件不支持这个参数），可以用maven-dependency-plugin先把所有依赖的类路径生成出来，再传给javadoc插件：

<build>
    <plugins>
        <!-- 第一步：生成项目依赖的类路径字符串，存到project.classpath属性里 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-dependency-plugin</artifactId>
            <version>3.6.0</version>
            <executions>
                <execution>
                    <id>build-classpath</id>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>build-classpath</goal>
                    </goals>
                    <configuration>
                        <outputProperty>project.classpath</outputProperty>
                        <pathSeparator>${path.separator}</pathSeparator>
                        <scope>compile+runtime</scope> <!-- 指定要包含的依赖范围 -->
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- 第二步：把生成的类路径传给自定义Doclet -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.5.0</version>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <doclet>com.yourpackage.YourCustomDoclet</doclet>
                <docletArtifact>
                    <groupId>com.yourgroup</groupId>
                    <artifactId>your-custom-doclet</artifactId>
                    <version>1.0.0</version>
                </docletArtifact>
                <!-- 传递生成的类路径给Doclet -->
                <additionalparam>-classpath ${project.classpath}</additionalparam>
            </configuration>
        </plugin>
    </plugins>
</build>

额外提醒 #

• 如果你的自定义Doclet是当前项目的一部分，不需要配置docletArtifact，直接写doclet全类名就行。
• 尽量用最新版的maven插件，旧版本可能存在一些兼容性问题。

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