site 生命周期

本章承接"生命周期概述"，讲解 site 生命周期。理解 pre-site、site、post-site、site-deploy 四个阶段的分工，是生成项目文档站点、对外展示项目信息、集成报告插件的基础。

核心机制

site 生命周期用于生成项目文档和报告，包含四个阶段：pre-site、site、post-site、site-deploy。说明：

site 阶段生成项目站点文档，site-deploy 阶段将生成的站点部署到远程服务器。这意味着 site 生命周期不仅能在本地生成 HTML 文档，还能像 mvn deploy 发布 JAR 一样，把文档站点发布到 Web 服务器。

site 生命周期的四个阶段

mvn site 的作用

当你执行 mvn site 时，Maven 会依次执行 pre-site → site → post-site。实际有可见效果的是 site 阶段，它绑定的 maven-site-plugin:site 目标会：

1. 解析 pom.xml 中的项目信息（名称、描述、开发者列表、许可证等）
2. 读取 src/site/ 目录下的自定义文档（如 Markdown、APT 格式）
3. 调用各种报告插件（如 maven-javadoc-plugin、maven-surefire-report-plugin）生成报告
4. 将所有内容渲染为 HTML 页面，输出到 target/site/ 目录

生成的站点内容

一个典型的 mvn site 输出包含：

生活类比：企业宣传册的制作与发行

想象飞翔科技要制作一本企业宣传册（项目文档站点）：

• pre-site = 素材准备：设计师收集公司介绍文案、产品照片、团队合影，确认印刷规格
• site = 排版印刷：设计师用排版软件（maven-site-plugin）将素材整合成册，同时插入各部门提交的报告（测试报告、API 文档、代码质量报告）。成品是一叠精美的宣传册（target/site/ 下的 HTML 文件）
• post-site = 装订质检：检查每本宣传册的页码顺序、图片清晰度，确保没有缺页
• site-deploy = 分发上架：将宣传册送到公司前台、展会展位、合作伙伴办公室（Web 服务器），让访客可以翻阅

这个类比的关键在于：site 生命周期关注的是"信息展示"而非"代码构建"。它把项目的技术信息（依赖树、测试报告、API 文档）转化为人类可读的网页，方便团队内外的人员快速了解项目状态。

图示

上图展示了 site 生命周期的阶段流程和 site 阶段的内部工作流。site 阶段是核心，它整合了项目元数据、自定义文档和各类报告插件的输出，最终渲染为统一的 HTML 站点。

完整示例

场景

飞翔科技的 employee-system 项目已经稳定运行，CTO 大翔希望有一个统一的页面，让新入职的员工（如即将加入的小崔的实习生）能快速了解项目结构、依赖情况和测试覆盖率。架构师白歌决定使用 mvn site 生成项目文档站点，并部署到公司内部 Wiki 服务器。

操作前：项目信息分散

在生成站点之前，项目信息分散在各处：

• 项目简介在 README.md 里
• 依赖列表需要手动查看 pom.xml
• 测试报告在 target/surefire-reports/ 的 XML 文件中，不易阅读
• API 文档需要单独执行 mvn javadoc:javadoc 生成
• 没有统一的入口让新人快速了解项目全貌

操作步骤

步骤 1：完善 pom.xml 的项目信息

白歌在 pom.xml 中补充了站点生成所需的元数据：

<project>
    ...
    <name>飞翔科技员工管理系统</name>
    <description>基于 Spring Boot 的企业级员工信息管理平台</description>
    <url>http://wiki.feixiang.tech/employee-system</url>

    <developers>
        <developer>
            <id>baige</id>
            <name>白歌</name>
            <email>baige@feixiang.tech</email>
            <roles>
                <role>架构师</role>
            </roles>
        </developer>
        <developer>
            <id>xiaocui</id>
            <name>小崔</name>
            <email>xiaocui@feixiang.tech</email>
            <roles>
                <role>后端开发</role>
            </roles>
        </developer>
    </developers>

    <issueManagement>
        <system>Jira</system>
        <url>http://jira.feixiang.tech/projects/EMP</url>
    </issueManagement>

    <ciManagement>
        <system>Jenkins</system>
        <url>http://jenkins.feixiang.tech/job/employee-system/</url>
    </ciManagement>
</project>

步骤 2：配置报告插件

白歌在 pom.xml 的 <reporting> 段中配置要生成的报告：

<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.1.2</version>
        </plugin>
    </plugins>
</reporting>

步骤 3：执行 site 生成

白歌执行：

mvn site

控制台输出（节选）：

[INFO] --- maven-site-plugin:3.12.1:site (default-site) @ employee-system ---
[INFO] Rendering site with locale zh_CN
[INFO] Rendering project reports...
[INFO] --- maven-javadoc-plugin:3.5.0:javadoc (default-cli) @ employee-system ---
[INFO] Generating /home/baige/employee-system/target/site/apidocs...
[INFO] --- maven-surefire-report-plugin:3.1.2:report (default-cli) @ employee-system ---
[INFO] Generating /home/baige/employee-system/target/site/surefire-report.html
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

步骤 4：查看生成的站点结构

target/site/
├── index.html                    # 项目首页
├── project-info.html             # 项目信息汇总
├── dependencies.html             # 依赖列表
├── dependency-info.html          # 如何引用本项目
├── javadoc/                      # API 文档
│   ├── index.html
│   ├── com/feixiang/employee/
│   │   ├── EmployeeService.html
│   │   └── EmployeeController.html
│   └── ...
├── surefire-report.html          # 测试报告
└── css/
    └── maven-base.css            # 站点样式

步骤 5：部署站点到服务器（可选）

白歌配置 pom.xml 中的站点部署地址：

<distributionManagement>
    <site>
        <id>company-wiki</id>
        <url>scp://wiki.feixiang.tech/var/www/employee-system/</url>
    </site>
</distributionManagement>

然后执行：

mvn site-deploy

站点被上传到公司内部 Wiki 服务器，访问 http://wiki.feixiang.tech/employee-system/ 即可查看。

操作结果

变化分析：

• 小崔的实习生入职第一天，通过站点首页就了解了项目背景、技术栈和团队分工
• 黄俪在联调时通过 dependencies.html 快速确认了 employee-system 使用的 Spring Boot 版本，避免了版本冲突
• 李眉在 Jenkins 流水线中增加了 mvn site 步骤，每次构建成功后自动生成最新测试报告，测试覆盖率趋势一目了然
• 大翔在周会上直接投影 surefire-report.html，向管理层展示项目的测试质量

易错点与常见问题

误区一：site 就是生成 Javadoc

错误认知："mvn site 不就是生成 Javadoc 吗？我直接运行 mvn javadoc:javadoc 就行了，没必要用 site。"

纠正：Javadoc 只是 site 生命周期生成的众多报告之一。mvn site 还会生成：

• 项目信息页（团队、许可证、 issue 管理链接）
• 依赖分析报告（传递依赖树、依赖冲突列表）
• 测试报告（测试通过率、耗时、失败详情）
• 代码质量报告（Checkstyle、PMD、SpotBugs 等，如配置了对应插件）

这些报告整合在一个统一的导航站点中，而 mvn javadoc:javadoc 只生成 API 文档。如果你需要"项目全貌文档"，必须用 mvn site。

误区二：site 生命周期没人用

错误认知："现在都用 Swagger 做 API 文档、用 SonarQube 做质量报告、用 Confluence 写项目文档，mvn site 生成的站点太丑、太弱，根本没人看。"

纠正：确实，mvn site 默认生成的站点样式朴素，功能不如专业工具强大。但它在以下场景仍有不可替代的价值：

• 离线环境：没有 SonarQube、没有 Confluence 的内网环境，mvn site 是零成本生成文档的手段
• CI/CD 集成：Jenkins 可以直接归档 target/site/ 目录，作为每次构建的附属产物，无需额外工具
• 依赖审计：dependencies.html 中的传递依赖树是排查依赖冲突的利器，很多专业工具反而没有这么直观的 Maven 专属视图
• 开源项目发布：发布到 Maven 中央仓库的开源项目，通常会在项目主页链接 mvn site 生成的站点，作为标准文档入口

误区三：site 和 deploy 会一起执行

错误认知："我执行 mvn deploy，Maven 应该会自动生成站点并一起部署吧？毕竟文档也是项目的一部分。"

纠正：mvn deploy 是 default 生命周期的阶段，只发布 JAR/WAR 等构建产物到远程仓库；mvn site-deploy 是 site 生命周期的阶段，只发布 HTML 文档到 Web 服务器。两者完全独立。如果你希望在发布版本的同时更新文档站点，需要显式执行组合命令：

mvn clean deploy site-deploy

或者配置 Jenkins 流水线，在 deploy 成功后触发 site-deploy。

小结

site 生命周期是 Maven 的"文档生成流水线"，由 pre-site、site、post-site、site-deploy 四个阶段组成。site 阶段通过 maven-site-plugin 整合项目元数据、自定义文档和各类报告插件的输出，渲染为统一的 HTML 站点。虽然现代开发中有 Swagger、SonarQube 等专业工具，但 mvn site 在离线环境、CI/CD 集成、依赖审计和开源项目发布等场景仍有独特价值。

本章与全局的关系：本章讲解了"如何生成项目文档站点"。下一章"生命周期与插件绑定"将打通生命周期的最后一块拼图——阶段如何与插件目标绑定，以及如何实现自定义绑定。