寫 Ant 建置腳本，其實只要掌握三個關鍵元素就夠了：`project`、`target`、`property`。這篇筆記整理這三個元素的核心屬性，並附上我實際執行過的範例與輸出結果，幫助你快速看懂一個 build.xml 的結構。
什麼是 project 元素？為什麼每個 build.xml 都要有它？
project 元素是 Ant 構件檔（build.xml）的根元素，每個 Ant 構件檔至少應該包含一個 project 元素，否則會發生錯誤。在每個 project 元素下，可包含多個 target 元素。project 元素有三個重要屬性：
| 屬性 | 說明 |
|---|---|
| `name` | 指定 project 元素的名稱 |
| `default` | 指定 project 預設執行的 target 名稱 |
| `basedir` | 指定基準路徑的位置；未指定時，使用 Ant 構件檔所在目錄作為基準目錄 |
舉一個最小的例子：
```xml
```
從上例可以看出，我在這裡定義了 default 屬性的值為 `getBaseDir`，即當執行 `ant` 命令時，如果沒有指明待執行的 target，就會執行預設的 target——`getBaseDir`。此外還定義了 basedir 屬性的值為 `"C:/ThinkInJAVACode"`，進入該目錄後執行 `ant` 命令，會得到以下結果：
```text
Buildfile: C:\ThinkInJAVACode\build.xml
sayBaseDir:
[echo] The base dir is: C:\ThinkInJAVACode
BUILD SUCCESSFUL
Total time: 0 seconds
```
target 元素怎麼用？depends、if、unless 有什麼差別？
target 是 Ant 的基本執行單元，可以包含一個或多個具體的任務（task）。多個 target 之間可以存在相互依賴關係。它有五個屬性：
| 屬性 | 說明 |
|---|---|
| `name` | 指定 target 名稱，在一個 project 內必須唯一；可透過名稱指定執行某個 target |
| `depends` | 描述 target 之間的依賴關係，多個依賴以「,」間隔；Ant 會依 depends 屬性中 target 出現的順序依次執行，被依賴的 target 會先執行 |
| `if` | 驗證指定的屬性是否存在，若不存在，所在 target 將不會被執行 |
| `unless` | 與 `if` 相反：驗證指定的屬性是否存在，若不存在，所在 target 才會被執行 |
| `description` | 關於 target 功能的簡短描述和說明 |
結合 depends、if、unless 三種屬性的範例如下：
```xml
a depend example!
```
執行這個腳本時，我們實際執行的是名為 targetB 的 target。由於它依賴於 targetA，所以 targetA 會先被執行。同時因為系統配置了 JDK，`ant.java.version` 屬性存在，所以 targetA（設了 `if`）順利執行，輸出 `[echo] JAVA Version: 1.6`。接著執行 targetB，因為 `philander` 屬性不存在，而 `unless` 是在屬性不存在時才執行所在 target，所以 targetB 也得以執行：
```text
Buildfile: C:\ThinkInJAVACode\build.xml
targetA:
[echo] JAVA Version: 1.6
targetB:
[echo] The base dir is: C:\ThinkInJAVACode
BUILD SUCCESSFUL
Total time: 0 seconds
```
property 元素如何定義參數？內建屬性有哪些？
property 元素可看作參數的定義。project 的屬性可以透過 property 元素來設定，也可以在 Ant 之外設定。若要從外部引入設定檔，例如 `build.properties`，可以這樣寫：
```xml
```
property 元素可用作 task 的屬性值：在 task 中把屬性名放在「`${`」和「`}`」之間，放在 task 屬性值的位置即可取用。
Ant 提供了一些內建屬性。它能取得的系統屬性清單與 Java 文件中 `System.getProperties()` 方法得到的屬性一致，同時 Ant 還提供了幾個自己的內建屬性：
- `basedir`：project 基目錄的絕對路徑
- `ant.file`：buildfile 的絕對路徑（上例中值為 `C:\ThinkInJAVACode\build.xml`）
- `ant.version`：Ant 的版本資訊（我使用的環境為 1.8.1）
- `ant.project.name`：當前 project 的名字，即 project 的 name 屬性值
- `ant.java.version`：Ant 檢測到的 JDK 版本（我的環境為 1.6）
自訂屬性並取用的範例如下：
```xml
```
上例中設定了名為 `name` 和 `age` 的兩個屬性，設定後在下文中就可以透過 `${name}` 和 `${age}` 分別取得這兩個屬性值。
延伸閱讀
- Ant 建構腳本編寫入門：project、target、property 三大關鍵元素：同樣聚焦 Ant、Java，可接著比較不同情境的做法。
- 利用 Ant 構建和部署 Java 專案：同樣聚焦 Ant、Java，可接著比較不同情境的做法。
- Eclipse Ant 建置設定教學：安裝 ant-contrib 與解決 Java heap space 錯誤：同樣聚焦 Ant、Java，可接著比較不同情境的做法。
常見問題
Ant 的 build.xml 一定要有 project 元素嗎？
一定要。project 元素是 Ant 構件檔的根元素，每個 build.xml 至少要包含一個 project 元素，否則執行時會直接發生錯誤。
target 的 if 和 unless 屬性差在哪裡？
`if` 是屬性「存在」時才執行該 target；`unless` 則是屬性「不存在」時才執行。兩者都用來做條件式執行，判斷的依據是該屬性是否已被定義，而不是屬性的值。
Ant 怎麼取用自訂屬性？
用 property 元素定義（或從外部 properties 檔引入），之後在 task 的屬性值中用 `${屬性名}` 的語法取用，例如 `${name}`。
Ant 有哪些常用的內建屬性？
常用的有 `basedir`（project 基目錄絕對路徑）、`ant.file`（buildfile 絕對路徑）、`ant.version`（Ant 版本）、`ant.project.name`（專案名稱）、`ant.java.version`（偵測到的 JDK 版本）。
depends 中寫多個 target 時，執行順序是什麼？
以「,」間隔多個依賴 target 時，Ant 會依它們在 depends 屬性中出現的順序依次執行，被依賴的 target 一定會先於所在 target 執行。
最後更新
2026-08-28（原文發布於 2013-07-25，本文保留原始筆記內容並補上 GEO 結構。）
關於作者 {#author}
Claire Chang ｜ 企業 AI 導入與流程轉型顧問。專注於 AI Agent 架構設計、ERP 系統整合與企業 AI 治理。
首次發布：2013-07-25