# 如何讓 Spring Boot 與 Maven 專案成功產製 site 文件站台

[Apache Maven](https://maven.apache.org/) 有個 [site](https://maven.apache.org/ref/3.8.1/maven-core/lifecycles.html#site_Lifecycle) 生命週期，定義出你要建立專案文件站台所需的各種階段，並讓你透過瀏覽器查看 Java 專案的完整資訊，相當方便。不過我透過 [Spring Initializr](https://start.spring.io/) 建立的專案，預設卻無法產生網站(site)，錯誤訊息也有點奇怪，逼的我還要去研究 Maven 才終於理解錯誤的原因。這篇文章我就來交代整個過程，以及解決方案。

### 設定步驟

1.  使用 [Spring Initializr](https://start.spring.io/) 工具建立一個以 [Apache Maven](https://maven.apache.org/) 為主的 [Spring Boot](https://spring.io/projects/spring-boot) 專案
    
    在 Visual Studio Code 執行 `F1` > `Spring Initializr: Create a Maven Project` 命令
    
    選擇 Spring Boot 版本： `2.5.3`
    
    選擇程式語言： `Java`
    
    輸入 Group Id： `com.duotify` (通常會輸入一個**組織名稱**或**群組名稱**)
    
    輸入 Artifact Id： `demo1` (這裡要輸入一個應用程式的唯一名稱，這會決定最後封裝的檔名)
    
    選擇封裝方式： `Jar`
    
    選擇 Java 版本： `11`
    
    選取相依套件： `Spring Web`, `Lombok`
    
    選擇一個資料夾： 假設我們選擇 `g:\Projects` 的話，他會自動建立一個 `g:\Projects\<artifactId>` 目錄，也就是 `g:\Projects\demo1`！
    
    右下角會彈出通知訊息，請按下 **Open** 按鈕直接開啟 Java 專案！
    
2.  開啟 `pom.xml` 並加入一個 `maven-site-plugin` 外掛 (Plugin)
    
    這裡最重要的設定，就是 `<version>` 標籤(Tag)，一定要加上，否則執行 `mvn site` 就會失敗！
    
    ```xml
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.9.1</version>
    </plugin>
    ```
    
3.  執行 `mvn site` 命令，產生專案文件的站台
    
    事實上這個命令會在 `target/site` 目錄下產生一個「網站」，裡面有多份 HTML 文件，也包含網頁所需的圖片、CSS、JS 等等，簡單來說，就是一個完整的網站！
    
    你可以利用 [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) 開啟 `target/site/index.html` 即可查看該專案的完整資訊。
    
    ![target/site/index.html](https://stwillblogassets.blob.core.windows.net/files/images/external/user-images.githubusercontent.com/7c66e4a21c5ff23c3080-129370642-edc0ed33-266c-4883-910b-bfc6dd262f91.png)
    
    > 你也可以執行 `mvn site:run` 啟動一個暫時的網站伺服器，預設會開 Port 8080，啟動後開啟瀏覽器到 [http://localhost:8080](http://localhost:8080) 就可以瀏覽文件。
    

### 原理說明

你從 Apache Maven 官網的 [Lifecycles Reference](https://maven.apache.org/ref/3.8.1/maven-core/lifecycles.html) 文件可以發現，Maven 在 `META-INF/plexus/components.xml` 定義了 3 個生命週期 (Lifecycles)，其中一個 `site` 生命週期定義如下：

```xml
<phases>
  <phase>pre-site</phase>
  <phase>site</phase>
  <phase>post-site</phase>
  <phase>site-deploy</phase>
</phases>
<default-phases>
  <site>
    org.apache.maven.plugins:maven-site-plugin:3.3:site
  </site>
  <site-deploy>
    org.apache.maven.plugins:maven-site-plugin:3.3:deploy
  </site-deploy>
</default-phases>
```

你可以看到這裡有定義 4 個階段 (phase)，而且其中兩個階段有設定**預設目標** (default goal)，其中 `default-phases` 定義的 `site` 預設目標設定到 `org.apache.maven.plugins:maven-site-plugin:3.3:site`，這個 `org.apache.maven.plugins:maven-site-plugin:3.3:site` 目標 (goal) 是這樣理解的：

-   `org.apache.maven.plugins` 是 `groupId`
-   `maven-site-plugin` 是 `artifactId`
-   `3.3` 是 `version`
-   `site` 是 `goal`

這就意味著你必須加裝 `maven-site-plugin` 到 `pom.xml` 的 `<plugins>` 清單中，讓你在執行 `site` 階段 (phase) 的時候 (`mvn site`)，才能夠「預設」觸發這個 `site` 目標。

不過 Spring Boot 其實有內建 `maven-site-plugin`，但是使用的版本為 `3.2.0`，太舊了，你必須升級到最新版才不會出現錯誤！🔥

### 相關連結

-   [Welcome to Apache Maven](https://maven.apache.org/)
-   [Maven Core - Lifecycles Reference](https://maven.apache.org/ref/3.8.1/maven-core/lifecycles.html#site_Lifecycle)
-   [Apache Maven Site Plugin - Introduction](https://maven.apache.org/plugins/maven-site-plugin/)
-   [Maven Repository: org.apache.maven.plugins » maven-site-plugin](https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-site-plugin)
-   [Download Apache Maven Site Plugin 3.9.1 Source](https://maven.apache.org/plugins/maven-site-plugin/download.cgi)
    -   Git Repo: `git clone https://gitbox.apache.org/repos/asf/maven-site-plugin.git`
    -   [Apache GitBox Repositories](https://gitbox.apache.org/repos/asf)