microlog4android 實現 Android 日誌寫入 SD 卡完整指南

前言

Android 開發中，由於設備碎片化嚴重，線上問題往往難以復現。將應用日誌持久化到 SD 卡，類似服務端的 Log4j，是定位疑難雜症的關鍵手段。microlog4android 是一款輕量級日誌框架，專為 Android 設計，支持 LogCat 與文件雙輸出。本文從依賴接入、配置詳解、常見坑點到自定義日誌路徑，提供完整落地指南。

快速接入步驟

1. 獲取依賴

官方下載頁：https://code.google.com/p/microlog4android/downloads/list
下載 microlog4android-1.0.0.jar 與 microlog.properties，放入項目 libs/ 目錄並加入構建路徑。

2. 聲明 Logger 實例

import net.sf.microlog.core.Logger;
import net.sf.microlog.core.LoggerFactory;

public class MainActivity extends Activity {
    private static final Logger logger = LoggerFactory.getLogger(MainActivity.class);
    // ...
}

3. 應用啟動時初始化（建議在 Application 或首個 Activity 的 onCreate）

import net.sf.microlog.midp.PropertyConfigurator;

@Override
public void onCreate() {
    super.onCreate();
    // 讀取 assets/microlog.properties 並自動配置
    PropertyConfigurator.getConfigurator(this).configure();
}

4. 放置配置文件

在 src/main/assets/（與 res/ 同級）創建 microlog.properties：

# 根日誌級別
microlog.level=DEBUG

# 雙輸出：LogCat + 文件
microlog.appender=LogCatAppender;FileAppender

# 格式化樣式
microlog.formatter=PatternFormatter
microlog.formatter.PatternFormatter.pattern=%c [%P] %m %T

5. 寫入日誌

logger.debug("網絡請求啟動: url=" + url);
logger.info("用戶登入成功: uid=" + uid);
logger.error("數據庫寫入失敗", e);  // 異常堆棧自動輸出

6. 聲明 SD 卡寫入權限

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

進階：自定義日誌文件路徑與名稱

默認情況下，日誌文件固定為 SD 卡根目錄下的 microlog.txt。若需自定義，需覆蓋 PropertyConfigurator 的解析邏輯。

問題根因

官方 1.0.0 版 JAR 中的 PropertyConfigurator 缺少 microlog.appender.FileAppender.File 屬性解析，導致配置無效。

解決方案：從源碼重新打包

1. 克隆源碼：git clone https://github.com/johanlkarlsson/microlog4android
2. 確認 PropertyConfigurator 包含 FileAppender.File 解析邏輯。
3. 導入項目，執行 ant jar 或用 IDE 導出為 microlog4android-1.1.jar。
4. 替換項目中的舊 JAR。

新配置示例

microlog.level=DEBUG
microlog.appender=FileAppender;LogCatAppender
microlog.appender.FileAppender.File=/sdcard/myapp/logs/mylog.txt
microlog.formatter=PatternFormatter
microlog.formatter.PatternFormatter.pattern=%d{%Y-%m-%d %H:%M:%S} %c [%P] %m %T

運行後，日誌將輸出至指定路徑，支持目錄自動創建（需確保權限）。

常見問題排查

遷移建議

microlog4android 更新停滯多年，缺乏日誌滾動、異步寫入、結構化日誌等現代特性。新項目建議直接採用：

• logback-android：Logback 官方 Android 移植，功能完整，性能優異。
• Timber：輕量封裝，適合調試階段，生產可接入任意後端。
• OkHttp Logging Interceptor：專注網絡日誌，配合上述框架使用。

總結

microlog4android 仍是舊項目快速加入文件日誌的可行方案。關鍵在於：使用支持 File 屬性的新版 JAR、正確配置 assets/microlog.properties、處理好運行時存儲權限。對於長期維護的項目，建議規劃遷移至 logback-android 等活躍維護的框架。