隨記

Gradle Build 生命週期與指令導覽

Gradle 基礎概念

Wrapper 機制

Gradle Wrapper 確保團隊使用相同版本的 Gradle，無需手動安裝。

gradle/
  wrapper/
    gradle-wrapper.jar      # Wrapper 執行檔
    gradle-wrapper.properties  # Wrapper 設定
gradlew           # Unix/Linux/Mac 執行腳本
gradlew.bat       # Windows 執行腳本

使用 Wrapper 的好處： - ✅ 版本一致性 - ✅ 自動下載正確版本 - ✅ CI/CD 環境友好

Build 生命週期

Gradle Build 分為三個階段：

1. 初始化階段 (Initialization)

作用： 決定哪些專案參與構建

執行 settings.gradle
  ↓
確定專案結構
  ↓
創建 Project 實例

相關文件： - settings.gradle - 定義專案名稱和子專案

範例：

rootProject.name = 'ERPOM'
// include 'subproject1', 'subproject2'  // 多專案配置

2. 配置階段 (Configuration)

作用： 評估 build script，配置所有 tasks

執行 build.gradle
  ↓
評估所有 task 配置
  ↓
建立 task 依賴關係圖

重點： - 所有 tasks 都會被配置（無論是否執行） - 插件（plugins）在此階段被應用 - 依賴（dependencies）在此階段被解析

範例：

apply plugin: 'java'
apply plugin: 'war'

dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web:2.1.2.RELEASE'
}

3. 執行階段 (Execution)

作用： 執行被選中的 tasks

根據指定的 task 名稱
  ↓
按照依賴順序執行 tasks
  ↓
完成構建

執行順序由以下決定： - Task 依賴關係 - dependsOn、mustRunAfter、shouldRunAfter 配置

常用指令

基本操作

1. 查看所有可用 Tasks

.\gradlew tasks

# 查看包含隱藏 tasks 的完整列表
.\gradlew tasks --all

2. 清理構建產物

.\gradlew clean

- 刪除 build/ 目錄 - 清除編譯產物、打包文件等

3. 編譯專案

# 編譯主代碼
.\gradlew compileJava

# 編譯測試代碼
.\gradlew compileTestJava

# 編譯所有代碼
.\gradlew classes

4. 執行測試

# 執行所有測試
.\gradlew test

# 跳過測試
.\gradlew build -x test

# 執行特定測試類
.\gradlew test --tests com.wpg.service.ConnectUrlServiceTest

5. 構建專案

# 完整構建（包含測試）
.\gradlew build

# 跳過測試的構建
.\gradlew build -x test

# 快速構建（跳過檢查）
.\gradlew assemble

6. 打包 WAR 文件

.\gradlew war

# 輸出位置：build/libs/ERPOM.war

依賴管理

1. 查看依賴樹

# 查看編譯依賴
.\gradlew dependencies --configuration compile

# 查看運行時依賴
.\gradlew dependencies --configuration runtime

# 查看所有配置的依賴
.\gradlew dependencies

2. 刷新依賴

# 強制刷新依賴（清除緩存）
.\gradlew build --refresh-dependencies

# 強制刷新快照版本
.\gradlew build --refresh-dependencies -Dorg.gradle.caching=false

3. 下載依賴到本地

.\gradlew downloadDependencies

專案資訊

1. 查看專案屬性

.\gradlew properties

2. 查看專案結構

.\gradlew projects

3. 查看 Task 詳細資訊

.\gradlew help --task build

進階操作

1. 並行構建（加速）

.\gradlew build --parallel

2. 持續構建模式

.\gradlew build --continuous
# 或簡寫
.\gradlew build -t

- 監視文件變化 - 自動重新構建

3. Debug 模式

# 詳細輸出
.\gradlew build --info

# Debug 級別輸出
.\gradlew build --debug

# Stack trace
.\gradlew build --stacktrace

4. Daemon 管理

# 停止 Gradle Daemon
.\gradlew --stop

# 不使用 Daemon 運行
.\gradlew build --no-daemon

5. 配置緩存

# 啟用配置緩存（加速配置階段）
.\gradlew build --configuration-cache

Task 依賴關係

Java 專案標準 Tasks

clean
  ↓
compileJava
  ↓
processResources
  ↓
classes
  ↓
compileTestJava
  ↓
processTestResources
  ↓
testClasses
  ↓
test
  ↓
jar / war
  ↓
assemble
  ↓
check
  ↓
build

Task 解釋

Task	說明	輸出
`clean`	刪除 build 目錄	-
`compileJava`	編譯 Java 源代碼	`build/classes/java/main/`
`processResources`	複製資源文件	`build/resources/main/`
`classes`	編譯所有主代碼	-
`compileTestJava`	編譯測試代碼	`build/classes/java/test/`
`processTestResources`	複製測試資源	`build/resources/test/`
`testClasses`	編譯所有測試代碼	-
`test`	執行單元測試	`build/reports/tests/`
`jar`	打包 JAR 文件	`build/libs/*.jar`
`war`	打包 WAR 文件	`build/libs/*.war`
`assemble`	組裝所有 archives	-
`check`	執行所有檢查（測試、lint等）	-
`build`	完整構建	-

實用範例

情境 1：本地開發快速構建

# 跳過測試，快速打包
.\gradlew clean build -x test

# 只編譯不打包
.\gradlew clean classes

情境 2：CI/CD 完整構建

# 完整構建，包含所有檢查
.\gradlew clean build --info

# 生產環境打包
.\gradlew clean war -Pprofile=production

情境 3：依賴問題排查

# 查看依賴衝突
.\gradlew dependencies | Select-String "FAILED"

# 強制刷新依賴
.\gradlew clean build --refresh-dependencies

# 清除 Gradle 緩存（極端情況）
Remove-Item -Recurse -Force $env:USERPROFILE\.gradle\caches
.\gradlew clean build

情境 4：編碼問題修復

# 指定編碼重新編譯
.\gradlew clean compileJava -Dfile.encoding=UTF-8

# 或在 gradle.properties 添加：
# org.gradle.jvmargs=-Dfile.encoding=UTF-8

情境 5：僅更新特定依賴

# 刷新特定配置的依賴
.\gradlew --refresh-dependencies dependencies --configuration compile

情境 6：多 Task 串聯執行

# 清理 → 構建 → 測試報告
.\gradlew clean build test jacocoTestReport

# 清理 → 編譯 → 跳過測試打包
.\gradlew clean compileJava war -x test

故障排查

問題 1：編譯錯誤 - 編碼問題

症狀： unmappable character for encoding UTF-8

解決方案：

# 方法 1: 命令行指定編碼
.\gradlew clean build -Dfile.encoding=UTF-8

# 方法 2: 在 build.gradle 添加
[compileJava, compileTestJava, javadoc]*.options*.encoding = 'UTF-8'

# 方法 3: 在 gradle.properties 添加
org.gradle.jvmargs=-Dfile.encoding=UTF-8

問題 2：依賴下載失敗

症狀： Could not resolve dependencies

解決方案：

# 1. 刷新依賴
.\gradlew clean build --refresh-dependencies

# 2. 清除緩存
Remove-Item -Recurse -Force $env:USERPROFILE\.gradle\caches

# 3. 檢查網路連接和代理設置
# 在 gradle.properties 添加代理（如需要）
systemProp.http.proxyHost=proxy.company.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.company.com
systemProp.https.proxyPort=8080

問題 3：Build 速度慢

優化方案：

# 1. 啟用並行構建
.\gradlew build --parallel

# 2. 啟用 Daemon（默認已啟用）
# 在 gradle.properties 添加
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true

# 3. 增加 Daemon 內存
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m

問題 4：Daemon 問題

症狀： Gradle Daemon 無響應或卡住

解決方案：

# 停止所有 Daemon
.\gradlew --stop

# 不使用 Daemon 運行
.\gradlew build --no-daemon

# 查看 Daemon 狀態
.\gradlew --status

問題 5：配置階段過慢

解決方案：

# 啟用配置緩存（Gradle 6.6+）
.\gradlew build --configuration-cache

# 在 gradle.properties 添加
org.gradle.configuration-cache=true

Gradle Wrapper 版本管理

查看當前版本

.\gradlew --version

升級 Wrapper 版本

# 升級到最新版本
.\gradlew wrapper --gradle-version=8.5

# 升級到特定版本
.\gradlew wrapper --gradle-version=7.6.3

使用特定發行版

# 使用完整發行版（包含源碼和文檔）
.\gradlew wrapper --gradle-version=8.5 --distribution-type=all

# 使用精簡版（默認）
.\gradlew wrapper --gradle-version=8.5 --distribution-type=bin

環境變數與配置

gradle.properties 配置範例

# JVM 設置
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8

# 並行構建
org.gradle.parallel=true

# 構建緩存
org.gradle.caching=true

# Daemon
org.gradle.daemon=true

# 配置緩存（Gradle 6.6+）
org.gradle.configuration-cache=true

# 代理設置（如需要）
# systemProp.http.proxyHost=proxy.company.com
# systemProp.http.proxyPort=8080

專案特定配置

在專案根目錄創建 gradle.properties 文件，覆蓋全局配置。

命令行參數優先級

命令行參數 > 專案 gradle.properties > 用戶 gradle.properties > 全局配置

總結

日常開發常用指令

# 快速構建（跳過測試）
.\gradlew clean build -x test

# 完整構建
.\gradlew clean build

# 查看依賴
.\gradlew dependencies

# 刷新依賴
.\gradlew build --refresh-dependencies

最佳實踐

✅ 使用 Gradle Wrapper，確保版本一致
✅ 啟用並行構建和緩存（gradle.properties）
✅ 開發時跳過測試加速（-x test）
✅ CI/CD 執行完整構建（包含測試）
✅ 定期清理緩存避免問題累積
✅ 使用 --info 或 --debug 排查問題

進階技巧

使用 --scan 生成構建掃描報告（需要註冊 Gradle Enterprise）
使用 --profile 生成性能報告
使用 --dry-run 預覽執行計劃
結合自定義 Task 實現專案特定需求

參考資源

Gradle 官方文檔
Gradle Build Lifecycle
Gradle Command-Line Interface
專案 build.gradle: d:\wpg\ERPOM\build.gradle
Wrapper 配置: d:\wpg\ERPOM\gradle\wrapper\gradle-wrapper.properties