使用 Maven 2 建立統一專案管理站點：完整配置指南

前言

Maven 2 不僅是建構工具，其強大的站點生成功能能為專案提供統一的資訊入口：專案介紹、成員名單、文件彙整、以及各類品質報表（Javadoc、測試覆蓋率、靜態分析等）。本文將從零開始，示範如何配置 Maven 產生專業的專案管理站點。

建立站點骨架

使用 Archetype 快速生成標準目錄結構：

mvn archetype:create \
 -DarchetypeGroupId=org.apache.maven.archetypes \
 -DarchetypeArtifactId=maven-archetype-site \
 -DgroupId=com.mycompany.app \
 -DartifactId=my-app-site

生成目錄結構包含 src/site 下的 apt、fml、xdoc 等文件格式目錄，以及核心配置檔 site.xml。

配置 pom.xml

1. 部署位置 (distributionManagement)

<distributionManagement>
  <site>
    <id>website</id>
    <url>scp://webhost.company.com/www/website</url>
  </site>
</distributionManagement>

2. 站點外掛配置 (maven-site-plugin)

設定語系為繁體中文（zh_CN）與編碼（GBK 或 UTF-8）：

<build>
  <plugins>
    <plugin>
      <artifactId>maven-site-plugin</artifactId>
      <configuration>
        <locales>zh_CN</locales>
        <outputEncoding>GBK</outputEncoding>
      </configuration>
    </plugin>
  </plugins>
</build>

編寫 site.xml：站點導覽結構

site.xml 定義站點佈局、橫幅、選單與連結：

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Maven">
  <bannerLeft>
    <name>Maven</name>
    <src>https://maven.apache.org/images/apache-maven-project.png</src>
    <href>https://maven.apache.org/</href>
  </bannerLeft>
  <bannerRight>
    <src>https://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <links>
      <item name="Apache" href="https://www.apache.org/"/>
      <item name="Maven 2" href="https://maven.apache.org/maven2/"/>
    </links>
    <menu name="Maven 2.0">
      <item name="Introduction" href="index.html"/>
      <item name="Download" href="download.html"/>
      <item name="Release Notes" href="release-notes.html"/>
    </menu>
    <menu ref="reports"/> <!-- 自動掛載報表選單 -->
  </body>
</project>

文件格式選擇

Maven 支援多種文件格式，建議採用 APT (Almost Plain Text) 格式，語法類似 Wiki，易讀易寫。若需支援中文，需使用 native2ascii 轉換編碼。

• .apt：一般文件
• .fml：FAQ 文件
• .xdoc：XML 文件

核心報表外掛配置 (reporting 區段)

在 <reporting><plugins> 中加入以下外掛，即可自動生成專業報表：

1. Javadoc (maven-javadoc-plugin)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <links>
      <link>https://java.sun.com/j2se/1.4.2/docs/api</link>
    </links>
    <aggregate>true</aggregate>
  </configuration>
</plugin>

2. PMD 程式碼分析 (maven-pmd-plugin)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-pmd-plugin</artifactId>
  <configuration>
    <rulesets>
      <ruleset>/rulesets/basic.xml</ruleset>
      <ruleset>/rulesets/unusedcode.xml</ruleset>
    </rulesets>
    <linkXref>true</linkXref>
    <sourceEncoding>GBK</sourceEncoding>
    <targetJdk>1.5</targetJdk>
  </configuration>
</plugin>

3. Checkstyle 程式碼風格檢查 (maven-checkstyle-plugin)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-checkstyle-plugin</artifactId>
  <configuration>
    <configLocation>sun_checks.xml</configLocation>
  </configuration>
</plugin>

4. 單元測試報表 (maven-surefire-report-plugin)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-report-plugin</artifactId>
</plugin>

5. 原始碼交叉參考 (maven-jxr-plugin)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jxr-plugin</artifactId>
</plugin>

6. 程式碼標籤清單 (taglist-maven-plugin)

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>taglist-maven-plugin</artifactId>
  <configuration>
    <tags>
      <tag>TODO</tag>
      <tag>FIXME</tag>
    </tags>
  </configuration>
</plugin>

生成與部署站點

• mvn site：在 target/site 生成靜態站點
• mvn site-deploy：依 distributionManagement 部署至遠端伺服器（需 SSH 金鑰配置）

結語

透過標準化的 site.xml、APT 文件與豐富的報表外掛，Maven 2 能以極低成本產出專業的專案管理站點，成為團隊溝通與品質把關的核心平台。建議將站點生成納入持續整合流程，每日自動更新，確保資訊即時性。