Timber Kotlin 日志库：完整指南与实战示例

1. 什么是 Timber？为什么需要它？

Timber 是一个轻量级的 Kotlin 日志库，专为 Android 应用设计。它由 Jake Wharton（Retrofit、OkHttp、Dagger 等知名项目的作者）开发。Timber 的核心目标是消除日志记录中的样板代码，并为不同开发阶段提供灵活的日志管理机制。

既然已经有标准的 android.util.Log，为什么还要用 Timber？首先，Timber 会自动在每个日志中添加类名和方法名，让调试追踪变得极其方便。你不再需要写 Log.d(TAG, "message")，只需调用 Timber.d("message") 即可。其次，Timber 提供了“树”（Trees）系统，允许你将日志分发到不同渠道：例如在 Debug 构建中输出到 Logcat，在 Release 构建中只将错误发送到 Crashlytics 或其他分析服务。

第三个重要优势是：如果你没有为生产环境配置专门的树，Timber 会在 Release 构建中自动禁用所有日志。这不仅提升了性能，还能防止敏感数据通过日志泄露。Timber 非常流行，被数千个商业项目使用，并且 Google 在官方 Android 开发指南中推荐使用它。

2. 安装指南

Timber 通过 Maven Central 分发。要安装，请在模块级别的 build.gradle 文件中添加依赖：

dependencies {
    implementation 'com.jakewharton.timber:timber:5.0.1'
}

如果你使用 Kotlin DSL（build.gradle.kts）：

dependencies {
    implementation("com.jakewharton.timber:timber:5.0.1")
}

同步 Gradle 后，库即可使用。注意：Timber 不需要在 AndroidManifest.xml 中添加额外权限。

3. 快速入门——最小可用示例

要开始使用，你需要“种一棵树”（plant a tree）——注册一个日志处理器。最简单的方法是使用内置的 Timber.DebugTree，它会将 DEBUG 及以上级别的日志输出到 Logcat：

import timber.log.Timber

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            Timber.plant(Timber.DebugTree())
        }
    }
}

现在，你可以在应用的任何地方记录日志：

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        Timber.d("Activity created")
        Timber.i("User opened main screen")
        Timber.w("Something suspicious happened")
        Timber.e("Error occurred: %s", "Network timeout")
    }
}

在 Logcat 中，你会看到类似下面的输出：

D/MainActivity: Activity created
I/MainActivity: User opened main screen
W/MainActivity: Something suspicious happened
E/MainActivity: Error occurred: Network timeout

注意：Timber 自动识别了类名（MainActivity）并将其添加到标签中。你无需手动创建 TAG 常量。

4. 核心方法/函数/类详解

4.1. Timber.d() — Debug 日志

方法签名： fun d(message: String, vararg args: Any?)

功能： 输出 DEBUG 级别的调试信息。用于开发过程中的临时日志。在 Release 构建中默认不输出。

Timber.