pd_log 0.1.2

Cross-platform logging plugin for Flutter with buffered native file logging.

pd_log

一个为 Flutter 提供跨平台、可缓冲文件写入的日志插件。

pd_log 旨在在不同平台（Android / iOS / macOS / Windows / Linux / Web）上提供一致的日志能力：

• 支持控制台打印与原生侧日志透传；
• 原生平台（Android / iOS / macOS / Windows / Linux）支持文件日志缓冲与定时/阈值刷新，提升性能与减少磁盘写入次数；
• 支持日志级别、标签、时间戳与可选调用者函数信息；
• 提供日志文件枚举、大小统计与删除能力；
• 统一的 Dart API，简单易用。

安装

• 在 pubspec.yaml 中添加依赖（示例使用首个公开测试版本 0.1.0）：

dependencies:
  pd_log: ^0.1.2

• 执行 flutter pub get。

快速开始

import 'package:pd_log/pd_log.dart';

void main() {
  // 配置日志（可根据需要修改各项配置）
  PDLog.configure(const PDLogConfig(
    defaultTag: 'MyApp',
    minLevel: LogLevel.debug,
    useNative: true,
    useConsole: true,
    showTimestamp: true,
    showCaller: false,
    nativeFileLoggingEnabled: true, // 启用原生文件日志缓冲
    nativeFileLoggingFlushIntervalMs: 2000, // 定时刷新间隔（毫秒）
    nativeFileLoggingMaxBufferEntries: 100, // 缓冲最大条数
    nativeFileLoggingMaxBufferBytes: 64 * 1024, // 缓冲最大字节数
  ));

  // 输出日志
  PDLog.d('App started');
  PDLog.i({'event': 'login', 'user': 'alice'});
  PDLog.e('Something went wrong', tag: 'Network');

  // 手动触发原生侧刷新，确保缓冲内容落盘
  PDLog.flushNativeLogs();
}

配置项说明（PDLogConfig）

• enabled：是否启用日志（默认 true）。
• minLevel：最小输出级别（默认 LogLevel.debug）。
• defaultTag：默认标签（可选）。
• useNative：是否透传到原生日志系统（默认 true）。
• useConsole：是否在 Dart 控制台打印（默认 true，仅 kDebugMode 下生效）。
• showTimestamp：是否在输出中加入时间戳（默认 true）。
• showCaller：是否显示调用者函数信息（默认 false，开启有少量性能开销）。
• nativeFileLoggingEnabled：是否启用原生文件日志缓冲（默认 false）。
• nativeFileLoggingFlushIntervalMs：定时刷新间隔（毫秒）。
• nativeFileLoggingMaxBufferEntries：最大缓冲条数（达到阈值触发刷新）。
• nativeFileLoggingMaxBufferBytes：最大缓冲字节数（达到阈值触发刷新）。

常用 API

• 级别日志：PDLog.v/d/i/w/e(Object? message, {String? tag})
• 手动刷新原生日志缓冲：PDLog.flushNativeLogs()
• 获取日志根目录：PDLog.logRootPath()
• 列出日志文件：PDLog.listLogFiles()（返回 List<PDLogFile>）
• 删除日志：PDLog.deleteLogFile(path)、PDLog.deleteAllLogFiles()
• 列出年份文件夹（原生实现）：PDLog.listYearFolders()

文件日志与缓冲策略

当启用 nativeFileLoggingEnabled 后，日志内容将会被透传到原生层，并由各平台的高性能缓冲与写入线程处理：

• 采用写线程与队列/条件变量避免主线程阻塞；
• 根据时间间隔与缓冲阈值触发刷新；
• 写入失败时，原生侧会安全地回填缓冲并重试，最大限度避免日志丢失。

示例项目

仓库内 example/ 目录提供了一个最小可运行示例，展示如何集成与使用 pd_log。你可以直接运行：

• flutter run -d <your-device>

支持平台

• Android / iOS / macOS / Windows / Linux / Web
• Web 端使用 console 输出；其他平台支持原生侧缓冲与文件写入。

常见问题（FAQ）

• 如何关闭控制台打印但保留文件日志？
  • 设置 useConsole: false 与 nativeFileLoggingEnabled: true。
• 是否会在 Release 模式打印控制台？
  • useConsole 仅在 kDebugMode 下生效，Release 默认不打印。
• 开启 showCaller 有性能影响吗？
  • 有少量开销，因为需要解析调用栈，建议仅在调试环境开启。

许可证

本项目基于 MIT 许可证开源，详见仓库根目录 LICENSE 文件。