首页 > 软件编程 > java > maven-site-plugin 使用

maven-site-plugin 插件的具体使用

2026-09-30 10:14:45 作者：程序员食堂

maven-site-plugin是 Maven 的一个核心插件,用于生成项目文档网站,本文就来详细的介绍一下如何使用,具有一定的参考价值,感兴趣的可以了解一下

maven-site-plugin 是 Maven 的一个核心插件，用于生成项目文档网站。以下是详细介绍：

主要功能

生成项目站点

集成各种项目报告（Javadoc、测试报告、检查报告等）
生成标准化的项目文档结构
支持多模块项目的聚合站点

报告集成

Javadoc API 文档
单元测试报告
代码覆盖率报告（配合 jacoco 等）
静态代码分析报告（Checkstyle、PMD、FindBugs）
项目信息（依赖、许可证、团队等）

常用 Goals

Goal	说明
site:site	生成项目站点（HTML 文件输出到 target/site/）
site:stage	将站点暂存到本地目录（用于多模块项目预览）
site:deploy	将生成的站点部署到配置的服务器（需配置 <distributionManagement>）
site:run	启动一个本地 HTTP 服务器预览站点（已弃用，建议用 mvn site + 本地打开 index.html）

注意：从 Maven Site Plugin 3.0+ 开始，site:run 已被移除。

基本配置

在 pom.xml 中配置

<project>
    <!-- 配置站点信息 -->
    <name>My Project</name>
    <description>项目描述</description>
    <url>https://example.com</url>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-site-plugin</artifactId>
                <version>3.12.1</version>  <!-- 使用最新版本 -->
            </plugin>
        </plugins>
    </build>
    
    <!-- 配置报告插件 -->
    <reporting>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.5.0</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-report-plugin</artifactId>
                <version>3.0.0</version>
            </plugin>
        </plugins>
    </reporting>
</project>

一键生成站点

mvn clean site

执行完后，静态站点位于 target/site/；用浏览器打开 target/site/index.html 即可查看。

常见增强项

中文站点 / UTF-8
在 <properties> 里加：

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

在插件<configuration>里加：

<locales>zh_CN</locales>

自定义输出目录

<configuration>
  <outputDirectory>${project.build.directory}/my-site</outputDirectory>
</configuration>

本地启服务实时预览

mvn site:run

会自动启动 Jetty，打开 http://localhost:8080 即可边改边看。

多模块项目

先生成整体站点，再一次性发布：

mvn site site:stage

site:stage 会把所有模块的页面聚合到 target/staging/ 目录，方便一次性拷贝到 nginx、Apache 或通过 site:deploy 上传到远程服务器。

与 AsciiDoc 集成（可选）

如果想用 .adoc 写文档，把文件放到 src/site/asciidoc/，然后在插件里增加依赖即可：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.12.1</version>
  <dependencies>
    <dependency>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>2.2.1</version>
    </dependency>
  </dependencies>
</plugin>

运行 mvn site 后会自动把 .adoc 渲染成 .html 并嵌入站点导航。

到此这篇关于maven-site-plugin 插件的具体使用的文章就介绍到这了,更多相关maven-site-plugin 使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！