如何配置Maven，使其为模块化项目生成站点

后端开发 2026-07-07

我有一个包含测试的JPMS模块化项目，我想用Maven site插件生成一个站点。我已经做了一个最小的项目来重现这个问题，它的地址在 here。

如果我运行 mvn site，就会出现一系列错误：

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.22.0:site (default-site) on project projectexample: Error generating maven-javadoc-plugin:3.12.0:test-aggregate-no-fork report:
[ERROR] Exit code: 1
[ERROR] D:\Libraries\Projects\mavenproject6\src\test\java\module-info.java:6: error: module name com.example.project.test does not match expected name com.example.project
[ERROR] module com.example.project.test {
[ERROR] ^
[ERROR] D:\Libraries\Projects\mavenproject6\src\test\java\module-info.java:8: error: module not found: junit
[ERROR]     requires junit;
[ERROR]              ^
[ERROR] D:\Libraries\Projects\mavenproject6\src\test\java\module-info.java:7: error: cyclic dependence involving com.example.project
[ERROR]     requires com.example.project;
[ERROR]                         ^
[ERROR] error: cannot access module-info
[ERROR]   cannot resolve modules
[ERROR] 4 errors

这个项目本身没问题，因为我可以用 mvn exec:java 运行它，用 mvn test 测试它。

我正在运行

Apache Maven 3.9.15 (98b2cdbfdb5f1ac8781f537ea9acccaed7922349)
Maven home: C:\Program Files\Apache NetBeans\java\maven
Java version: 25, vendor: Eclipse Adoptium, runtime: C:\Program Files\Eclipse Adoptium\jdk-25.0.0.36-hotspot
Default locale: en_GB, platform encoding: UTF-8
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

POM文件是：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>projectexample</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.13.2</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.release>25</maven.compiler.release>
        <exec.mainClass>com.example.project.Example</exec.mainClass>
    </properties>
    <reporting>
        <plugins>
            <plugin>
                <artifactId>maven-project-info-reports-plugin</artifactId>
                <version>3.9.0</version>
            </plugin>
            <plugin>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.12.0</version>

            </plugin>

        </plugins>
    </reporting>
    <build>
        <plugins>
            <plugin>
                <artifactId>maven-site-plugin</artifactId>
                <version>3.22.0</version>
            </plugin>
        </plugins>
    </build>
</project>

以及目录结构是

D:.
|   pom.xml
|
+---src
|   +---main
|   |   \---java
|   |       |   module-info.java
|   |       |
|   |       \---com
|   |           \---example
|   |               \---project
|   |                       Example.java
|   |
|   \---test
|       \---java
|           |   module-info.java
|           |
|           \---com
|               \---example
|                   \---project
|                       \---test
|                               ExampleTest.java
|
\---target

这两个module-info文件是（第一个是 main）：

module com.example.project {
    exports com.example.project;
}

以及（第二个是针对 'test' 的）：

module com.example.project.test {
    requires com.example.project;
    requires junit;
    opens com.example.project.test to junit;
}

如果我移除测试部分的 module-info.java、mvn test 和 exec:java，仍然可以工作，但会从 mvn site 收到不同的错误：

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.22.0:site (default-site) on project projectexample: Error generating maven-javadoc-plugin:3.12.0:test-aggregate-no-fork report:
[ERROR] Exit code: 1
[ERROR] D:\Libraries\Projects\mavenproject6\src\test\java\com\example\project\test\ExampleTest.java:4: error: package org.junit does not exist
[ERROR] import org.junit.Test;
[ERROR]                 ^
[ERROR] D:\Libraries\Projects\mavenproject6\src\test\java\com\example\project\test\ExampleTest.java:5: error: package org.junit does not exist
[ERROR] import static org.junit.Assert.*;
[ERROR]                        ^
[ERROR] D:\Libraries\Projects\mavenproject6\src\test\java\com\example\project\test\ExampleTest.java:12: error: cannot find symbol
[ERROR]     @Test
[ERROR]      ^
[ERROR]   symbol:   class Test
[ERROR]   location: class ExampleTest
[ERROR] 3 errors

编辑1： 基于JF Meier的提问提供的更多信息

[ERROR] /private/tmp/maven-site-example/src/test/java/module-info.java:6: error: module name com.example.project.test does not match expected name com.example.project

我把模块重命名为 com.example.project，显然也必须移除 require com.example.project。预期的名称错误解决了，但我仍然得到：

[ERROR] /private/tmp/maven-site-example/src/test/java/module-info.java:7: error: module not found: junit
[ERROR]     requires junit;

在我的任何尝试中移除 requires junit 都会导致 mvn test 失败。

另外我还调查了建立site目标的成分。错误来自javadoc插件，具体来自目标 javadoc:test-aggregate-no-fork

% mvn -B javadoc:test-aggregate-no-fork
[INFO] Scanning for projects...
[INFO] 
[INFO] ---------------------< com.example:projectexample >---------------------
[INFO] Building projectexample 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- javadoc:3.12.0:test-aggregate-no-fork (default-cli) @ projectexample ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.587 s
[INFO] Finished at: 2026-06-29T19:20:47+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.12.0:test-aggregate-no-fork (default-cli) on project projectexample: An error has occurred in Test Javadoc report generation: 
[ERROR] Exit code: 1
[ERROR] /private/tmp/maven-site-example/src/test/java/module-info.java:6: error: module name com.example.project.test does not match expected name com.example.project
[ERROR] module com.example.project.test {
[ERROR] ^
[ERROR] /private/tmp/maven-site-example/src/test/java/module-info.java:8: error: module not found: junit
[ERROR]     requires junit;
[ERROR]              ^
[ERROR] /private/tmp/maven-site-example/src/test/java/module-info.java:7: error: cyclic dependence involving com.example.project
[ERROR]     requires com.example.project;
[ERROR]                         ^
[ERROR] error: cannot access module-info
[ERROR]   cannot resolve modules
[ERROR] 4 errors
[ERROR] Command line was: /opt/homebrew/Cellar/openjdk/26.0.1/libexec/openjdk.jdk/Contents/Home/bin/javadoc -J-Duser.language= -J-Duser.country= @options @argfile
[ERROR] 
[ERROR] Refer to the generated Javadoc files in '/private/tmp/maven-site-example/target/reports/testapidocs' dir.
[ERROR] -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

确实目标 javadoc:test-aggregate 也有同样的问题。所以我认为需要去研究那个插件，而不是site插件。

编辑2：

作为一种变通方法，我将javadoc插件配置为仅生成javadoc和 test-javadoc报告，跳过聚合报告（说实话我也不需要看到测试的javadoc）

<reporting>
    <plugins>
        <plugin>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.12.0</version>
...
            <reportSets>
                <reportSet>
                    <!-- default set -->
                    <reports>
                        <report>javadoc</report>
                        <report>test-javadoc</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>