Log4j 設定檔深度解析：Appender、Layout 與等級控制完整指南

Log4j 作為 Apache 經典的日誌框架，憑藉「配置檔驅動、無需修改代碼即可靈活控制日誌輸出」的特性，長期佔據 Java 專案日誌選型的主流地位。本文系統梳理 Log4j 核心組件——優先級、Appender（輸出目的地）、Layout（輸出格式）的配置細節，並附上實戰範例，助你快速掌握企業級日誌配置精髓。

一、Log4j 三大核心優勢

• 多樣化輸出目的地：透過配置檔即可將日誌導向 Console、File、GUI、Socket Server、JMS、NT Event Log、Syslog 等，零代碼變更。
• 精細的等級控制：開發階段開啟 DEBUG 追蹤細節，生產環境切換至 WARN/ERROR 降低噪音與 I/O 開銷，告別 System.out.println 汙染代碼。
• 統一規格：全專案單一 Log 機制，利於團隊協作與維護。

二、核心組件詳解

1. 日誌優先級

標準等級由高到低：FATAL > ERROR > WARN > INFO > DEBUG > TRACE > ALL。建議實務上僅使用 ERROR, WARN, INFO, DEBUG 四級。Logger 設定的等級為「閾值」，低於該等級的日誌請求將被忽略。

2. Appender：日誌去向的掌舵者

一個 Logger 可掛載多個 Appender，日誌事件會廣播至所有掛載的 Appender 及父 Logger 的 Appender。

常用 Appender 類型與關鍵屬性

3. Layout：定義日誌長相

主流 Layout 及適用場景：

• PatternLayout：最靈活，透過 Conversion Pattern 自定義格式（推薦）。
• HTMLLayout：產出 HTML 表格，適合郵件報表或 Web 監控頁。
• SimpleLayout：僅含等級與訊息，極簡場景適用。
• TTCCLayout：含時間、線程、類別等完整上下文，適合多線程追蹤。

PatternLayout 常用轉換字符速查

%m  代碼中指定的訊息
%p  優先級 (DEBUG/INFO/WARN/ERROR/FATAL)
%r  應用啟動至今毫秒數
%c  Logger 名稱 (通常為全類名)
%t  線程名
%n  換行符 (Windows \r\n, Unix \n)
%d  日期時間，可指定格式如 %d{yyyy-MM-dd HH:mm:ss,SSS}
%l  呼叫位置 (類.方法:行號)，性能開銷大，慎用

三、進階技巧：為不同 Appender 設定不同閾值

透過 Threshold 屬性，可讓同一 Logger 的不同 Appender 只處理特定等級以上的日誌。經典案例：Console 輸出 INFO 以上，主日誌檔記錄 DEBUG 以上，錯誤專檔僅收 ERROR。

log4j.rootLogger=DEBUG, Console, File, ErrorFile

# Console 輸出
log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.Target=System.out
log4j.appender.Console.layout=org.apache.log4j.PatternLayout
log4j.appender.Console.layout.ConversionPattern=%p %t %c - %m%n

# 主日誌檔 (每日滾動，DEBUG 以上)
log4j.appender.File=org.apache.log4j.DailyRollingFileAppender
log4j.appender.File.File=logs/app.log
log4j.appender.File.Append=true
log4j.appender.File.Threshold=DEBUG
log4j.appender.File.layout=org.apache.log4j.PatternLayout
log4j.appender.File.layout.ConversionPattern=%p %t %c - %m%n

# 錯誤專檔 (每日滾動，僅 ERROR)
log4j.appender.ErrorFile=org.apache.log4j.DailyRollingFileAppender
log4j.appender.ErrorFile.File=logs/error.log
log4j.appender.ErrorFile.Append=true
log4j.appender.ErrorFile.Threshold=ERROR
log4j.appender.ErrorFile.layout=org.apache.log4j.PatternLayout
log4j.appender.ErrorFile.layout.ConversionPattern=%p %t %c - %m%n

四、完整程式碼驗證範例

import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class Log4jDemo {
    private static final Logger logger = Logger.getLogger(Log4jDemo.class);

    public static void main(String[] args) {
        // 載入外部配置檔
        PropertyConfigurator.configure("conf/log4j.properties");

        logger.debug("除錯資訊：進入業務邏輯");
        logger.info("一般資訊：訂單建立成功");
        logger.warn("警告：庫存低於安全閾值");
        logger.error("錯誤：支付閘道超時", new RuntimeException("模擬異常"));
    }
}

五、避坑指南

1. 檔案路徑問題：File 屬性建議使用相對專案根目錄或絕對路徑，避免部署環境差異導致找不到檔案。
2. 編碼設定：若日誌含中文，建議在 JVM 參數加入 -Dfile.encoding=UTF-8，或在 Layout 指定 Encoding=UTF-8（需 Log4j 1.2.17+）。
3. 非同步提升性能：高併發場景可包裝 AsyncAppender 降低業務線程阻塞。
4. 避免重複配置：rootLogger 已掛載 Appender 時，子 Logger 設定 additivity=false 可防止日誌重複輸出。

結語

Log4j 雖歷經 Log4j2 迭代，但 1.x 版本仍廣泛存量於存量專案。掌握其配置邏輯，不僅能快速維護舊系統，更能深入理解現代日誌框架（Logback, Log4j2）的設計哲學——關注點分離、配置外部化、零侵入業務代碼。