【maven】maven-site-plugin 插件

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

主要功能

1. 生成项目站点

   • 集成各种项目报告（Javadoc、测试报告、检查报告等）

   • 生成标准化的项目文档结构

   • 支持多模块项目的聚合站点

2. 报告集成

   • 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 并嵌入站点导航。

---

---

---