Maven 项目文档
Maven 项目文档生成（Site + Javadoc + 报告）完全指南（2025 最新版）
一句话总结：
一行命令生成完整项目站点：文档、API、测试报告、依赖分析、代码覆盖率！
一、Maven Site 生命周期
pre-site → site → post-site → site-deploy| 命令 | 作用 |
|---|---|
mvn site | 生成站点 → target/site/ |
mvn site:deploy | 发布到服务器 |
二、启用 Site（pom.xml 配置）
<project>
...
<build>
<plugins>
<!-- Site 插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>4.0.0</version>
</plugin>
<!-- 项目信息插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>3.5.0</version>
</plugin>
</plugins>
</build>
<!-- 报告插件 -->
<reporting>
<plugins>
<!-- Javadoc -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>17</source>
<encoding>UTF-8</encoding>
<doclint>all,-missing</doclint>
</configuration>
</plugin>
<!-- 单元测试报告 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>3.2.5</version>
</plugin>
<!-- 代码覆盖率 -->
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.12</version>
</plugin>
<!-- 依赖分析 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>3.5.0</version>
</plugin>
</plugins>
</reporting>
</project>三、生成文档命令
# 1. 生成站点 + 所有报告
mvn clean site
# 2. 查看结果
open target/site/index.html # macOS
# 或 Windows: start target/site/index.html四、生成的文档内容（target/site/）
| 文件 | 说明 |
|---|---|
index.html | 首页 |
project-info.html | 项目信息（GAV、许可证） |
dependencies.html | 依赖树 |
dependency-convergence.html | 依赖冲突 |
javadoc/ | API 文档 |
surefire-report.html | 单元测试报告 |
jacoco/ | 代码覆盖率 |
project-reports.html | 所有报告入口 |
五、自定义站点（src/site/）
my-project/
├── src/
│ └── site/
│ ├── site.xml ← 菜单配置
│ ├── markdown/
│ │ └── README.md ← 自定义页面
│ └── resources/
│ └── css/style.csssite.xml 示例
<?xml version="1.0" encoding="UTF-8"?>
<project name="My App" xmlns="http://maven.apache.org/DECORATION/1.8.0">
<bannerLeft>
<name>My App</name>
<href>./index.html</href>
</bannerLeft>
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="Quick Start" href="markdown/quickstart.html"/>
</menu>
<menu ref="reports"/>
</body>
</project>Markdown 页面
<!-- src/site/markdown/quickstart.md -->
# 快速开始java
public class App {
public static void main(String[] args) {
System.out.println(“Hello Maven Site!”);
}
}
```
---
## 六、Javadoc 单独生成bash
生成 Javadoc JAR
mvn javadoc:jar
生成聚合 Javadoc（多模块）
mvn javadoc:aggregate
输出：`target/site/apidocs/`
---
## 七、代码覆盖率（JaCoCo）xml
org.jacoco jacoco-maven-plugin 0.8.12 prepare-agent report test report
运行：bash
mvn test
open target/site/jacoco/index.html
---
## 八、完整命令速查
| 命令 | 作用 |
|------|------|
| `mvn site` | 生成站点 |
| `mvn site:deploy` | 发布到服务器 |
| `mvn javadoc:jar` | 打包 Javadoc |
| `mvn surefire-report:report` | 仅生成测试报告 |
| `mvn site -DgenerateReports=false` | 只生成自定义页面 |
---
## 九、发布站点（`site:deploy`）xml
github-pages scm:git:git@github.com:username/repo.git?gh-pages
bash
mvn site:deploy
> **GitHub Pages**：自动发布到 `https://username.github.io/repo`
---
## 十、模板：完整 `pom.xml`（含文档）xml
org.apache.maven.plugins maven-site-plugin 4.0.0
org.apache.maven.plugins maven-javadoc-plugin 3.7.0 org.apache.maven.plugins maven-surefire-report-plugin 3.2.5 org.jacoco jacoco-maven-plugin 0.8.12
“`
十一、IDEA 集成
- Maven 面板 →
site→ 双击运行 - 右键
pom.xml→ Maven → site - 自动打开
target/site/index.html
十二、推荐工具
| 工具 | 作用 |
|---|---|
| Asciidoctor | Markdown → HTML |
| Doxia | Maven 原生文档 |
| GitHub Pages | 免费发布 |
恭喜！你已掌握 Maven 项目文档生成！
下一步推荐
| 方向 | 内容 |
|---|---|
| GitHub Pages 自动发布 | Actions + site:deploy |
| Asciidoctor 文档 | .adoc 编写 |
| Confluence 集成 | 导出 HTML |
需要 GitHub Actions 自动发布文档脚本？
回复 GitHub Site 立即获取！