HOWTO · Java
Java 中的屬性檔案
本文討論 Java 中的屬性檔案。
本頁內容
Java 的 Properties 類別會以鍵值配對的方式儲存應用程式設定，通常存放在副檔名為 .properties 的檔案中。使用 setProperty() 新增字串鍵和值、用 store() 儲存、用 load() 讀取，再透過 getProperty() 取得指定設定。list() 則可顯示已載入的項目，方便檢視。
在 Java 屬性檔案中建立並設定值
使用 .properties 檔案在 Java 教學 的檔案 IO 與屬性分組中講解，Java 設定類指南都匯集在那裡。
屬性檔案每行包含一個項目。例如，version=1.1 和 projectName=PropertiesFileExample 是兩個不同的項目；以 # 或 ! 開頭的行則是註解。鍵和值之間可用 =、: 或空白分隔。鍵前面的空白會被忽略，而值可以包含空格。使用 setProperty() 新增每組鍵值，再呼叫 store() 寫入整個集合，也可以一併寫入註解。
執行以下範例：
本節中的程式碼以及顯示的標籤或輸出仍為英文。
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
public class JavaExample {
public static void main(String[] args) throws IOException {
Path directory = Files.createTempDirectory("properties-demo-");
Path file = directory.resolve("myConfigs.properties");
Properties properties = new Properties();
properties.setProperty("version", "1.1");
properties.setProperty("projectName", "PropertiesFileExample");
properties.setProperty("date", "2021/12/27");
try (OutputStream output = Files.newOutputStream(file)) {
properties.store(output, "Application settings");
}
}
}
Files.newOutputStream() 會在檔案不存在時建立檔案；若檔案已存在，則會先清空原有內容。檔案的上層目錄必須已存在，因此此範例會先建立暫存目錄。即使寫入失敗，try-with-resources 區塊仍會關閉串流。若改用固定路徑，請先建立其上層目錄，再開啟檔案。除了項目之外，store() 也會寫入註解和自動產生的時間戳記，因此這些註解行每次執行時可能不同。使用 OutputStream 時，非拉丁字元會依屬性檔案格式轉義；使用 Writer 則可明確指定字元編碼。
若程式使用 java.io，new FileOutputStream(path) 也會在檔案不存在時建立檔案，並在檔案已存在時清空內容；它同樣要求上層目錄已存在。請像上方的串流一樣，使用 try-with-resources 關閉它。
從 Java 屬性檔案取得指定屬性
若要取得某項設定，請開啟已儲存的檔案以供讀取，在 Properties 物件上呼叫 load()，再將所需的鍵傳給 getProperty()。此範例在同一次執行中寫入並讀取檔案，因此不必依賴其他程式先前留下的檔案。輸入串流也使用 try-with-resources，載入完成後便會關閉檔案。
本節中的程式碼以及顯示的標籤或輸出仍為英文。
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
public class JavaExample {
public static void main(String[] args) throws IOException {
Path directory = Files.createTempDirectory("properties-demo-");
Path file = directory.resolve("myConfigs.properties");
Properties saved = new Properties();
saved.setProperty("date", "2021/12/27");
try (OutputStream output = Files.newOutputStream(file)) {
saved.store(output, "Application settings");
}
Properties loaded = new Properties();
try (InputStream input = Files.newInputStream(file)) {
loaded.load(input);
}
String date = loaded.getProperty("date");
System.out.println(date == null ? "No date setting" : date);
}
}
如果找不到指定的鍵，getProperty() 會回傳 null，不會因此擲出錯誤。若設定是選填的，請檢查是否為 null；也可以使用 getProperty("theme", "light") 提供預設值。檔案不存在、路徑無法讀取或發生其他檔案存取問題，則是不同情況：開啟或載入檔案時可能會擲出 IOException。請在應用程式邊界處理這類例外，提供有用的訊息，或交由呼叫端決定如何復原。範例在 main 上宣告 IOException，讓讀取流程更清楚；正式應用程式通常會在能提供適當脈絡的位置捕捉例外。
從 Java 屬性檔案取得所有鍵和值
若要快速在主控台檢視內容，請載入檔案，再將 System.out 傳給 list()。以下完整範例會先建立自己的輸入檔案，再顯示載入的項目。範例也加入第二項設定，讓輸出展示多組鍵值配對。
本節中的程式碼以及顯示的標籤或輸出仍為英文。
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
public class JavaExample {
public static void main(String[] args) throws IOException {
Path directory = Files.createTempDirectory("properties-demo-");
Path file = directory.resolve("myConfigs.properties");
Properties saved = new Properties();
saved.setProperty("version", "1.1");
saved.setProperty("projectName", "PropertiesFileExample");
try (OutputStream output = Files.newOutputStream(file)) {
saved.store(output, "Application settings");
}
Properties loaded = new Properties();
try (InputStream input = Files.newInputStream(file)) {
loaded.load(input);
}
loaded.list(System.out);
}
}
list() 適合產生易讀的診斷清單，不是通用的迭代 API。它的呈現方式和項目順序都不是穩定格式，不適合用來解析或比較。如果應用程式需要處理各項資料，請改為迭代 Properties 的項目或鍵，並將每個值視為字串處理。若順序或註解很重要，請以原始檔案為準：儲存屬性是為了保存設定資料，而 list() 只會呈現目前載入記憶體的值。
