配置Javadoc后Site报告缺失，已执行指定配置仍未解决

Hey there, I’ve dealt with this exact missing Site report issue a few times before—super frustrating when you think you’ve set up the doclint disable correctly and it still doesn’t work. Let’s walk through what might be going wrong and get your Site report showing up again.

Common Reasons Your Configuration Might Be Failing #

• Incomplete or misaligned doclint parameters: Depending on your JDK version, the way to disable doclint changes. JDK 8 uses -Xdoclint:none as an additional parameter, while JDK 9+ supports a direct <doclint>none</doclint> configuration option. If you’re only using one or the other, it might not be taking effect.
• Plugin version mismatches: Older versions of maven-site-plugin or maven-javadoc-plugin might not properly handle the doclint disable settings, or have bugs in how they integrate.
• Missing standalone Javadoc configuration: If your base maven-javadoc-plugin isn’t configured to skip doclint, the Site report generation might fail silently when trying to generate Javadocs under the hood.

Step-by-Step Working Configuration #

Here’s a complete, tested setup that covers both JDK 8 and newer versions, and ensures the Site report includes your Javadocs:

First, define the doclint option in your properties (for reusability):

<properties>
    <!-- For JDK 8 -->
    <javadoc.opts>-Xdoclint:none</javadoc.opts>
</properties>

Then, configure the standalone maven-javadoc-plugin to ensure Javadocs generate successfully on their own:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.6.0</version>
            <configuration>
                <!-- Apply JDK 8 parameter -->
                <additionalparam>${javadoc.opts}</additionalparam>
                <!-- For JDK 9+, replace the above line with this: -->
                <!-- <doclint>none</doclint> -->
                <skip>false</skip>
            </configuration>
        </plugin>
    </plugins>
</build>

Finally, update your maven-site-plugin to use the same Javadoc configuration for the report:

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.12.1</version>
            <reportPlugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>3.6.0</version>
                    <configuration>
                        <additionalparam>${javadoc.opts}</additionalparam>
                        <!-- Again, use <doclint>none</doclint> for JDK 9+ -->
                        <skip>false</skip>
                        <!-- Ensure the report is explicitly enabled -->
                        <reportOutputDirectory>${project.reporting.outputDirectory}/apidocs</reportOutputDirectory>
                    </configuration>
                </plugin>
            </reportPlugins>
        </plugin>
    </plugins>
</reporting>

How to Verify #

1. First, run mvn javadoc:javadoc directly. If this fails, fix those errors first—this confirms your Javadoc configuration is working before checking the Site report.
2. Then run mvn site and check the generated site (usually in target/site). The Javadoc report should now be present under the "Project Reports" section.

Bonus Troubleshooting Tip #

If it still doesn’t work, check the full Maven build logs with mvn site -X (debug mode). Look for lines related to maven-javadoc-plugin—you’ll often see specific errors (like unclosed tags or missing parameters) that the doclint disable didn’t cover, or issues with plugin version compatibility.

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