更新记录

1.0.0（2025-12-19） 下载此版本

新增

• 初始版本发布
• 支持 DEBUG、INFO、WARN、ERROR 四种日志级别
• 支持本地文件写入和控制台输出
• 支持自动清理过期日志
• 支持日志文件大小限制和自动分片
• 支持读取和导出日志文件
• 支持自定义初始化配置
• 支持多实例（createLogCat 工厂函数）
• 支持日志写入回调
• 支持动态更新配置
• 完整的 TypeScript 类型支持

平台兼容性

uni-app(3.6.15)

uni-app x(3.6.15)

gp-logcat

UniApp Android 日志记录插件，支持本地文件存储和控制台输出。

特性

• 支持 DEBUG、INFO、WARN、ERROR 四种日志级别
• 自动写入本地文件，按日期分文件存储
• 自动清理过期日志文件
• 支持日志文件大小限制和自动分片
• 支持读取和导出日志文件
• 完整的 TypeScript 类型支持
• 支持自定义配置和格式化
• 支持多实例（可创建多个独立的日志管理器）

安装

将插件导入到 uni_modules 目录即可。

快速开始

基础使用

import { LogCat } from '@/uni_modules/gp-logcat';

// 初始化（建议在 App.vue 的 onLaunch 中调用）
LogCat.init();

// 记录日志
LogCat.debug('调试信息', { userId: 123 });
LogCat.info('普通信息');
LogCat.warn('警告信息');
LogCat.error('错误信息', new Error('发生错误'));

带配置初始化

import { LogCat, LogLevel } from '@/uni_modules/gp-logcat';

LogCat.init({
  // 日志保存天数
  saveDays: 7,
  // 日志文件名前缀
  filePrefix: 'myapp',
  // 是否启用控制台输出
  enableConsole: true,
  // 是否启用文件写入
  enableFileWrite: true,
  // 最低日志级别
  minLevel: LogLevel.INFO,
  // 日志标签
  tag: 'MyApp',
  // 日志目录名称
  logDirName: 'logs',
  // 单个文件最大大小（字节）
  maxFileSize: 5 * 1024 * 1024,
  // 是否在初始化时清理过期日志
  cleanOnInit: true,
});

使用快捷方法

import { initLogCat, logDebug, logInfo, logWarn, logError } from '@/uni_modules/gp-logcat';

// 初始化
initLogCat({ saveDays: 7 });

// 记录日志
logDebug('调试信息');
logInfo('普通信息');
logWarn('警告信息');
logError('错误信息');

创建独立实例

import { createLogCat, LogLevel } from '@/uni_modules/gp-logcat';

// 创建独立的日志实例
const networkLogger = createLogCat({
  tag: 'Network',
  filePrefix: 'network',
  minLevel: LogLevel.INFO,
});

networkLogger.init();
networkLogger.info('请求发送', { url: '/api/user' });

API 文档

初始化配置项 (LogCatOptions)

方法

init(options?: LogCatOptions): boolean

初始化日志系统。

const success = LogCat.init({ saveDays: 7 });

destroy(): void

销毁日志系统，释放资源。

LogCat.destroy();

debug(message: string, data?: unknown): void

记录 DEBUG 级别日志。

LogCat.debug('用户点击按钮', { buttonId: 'submit' });

info(message: string, data?: unknown): void

记录 INFO 级别日志。

LogCat.info('用户登录成功', { userId: 123 });

warn(message: string, data?: unknown): void

记录 WARN 级别日志。

LogCat.warn('API 响应较慢', { duration: 3000 });

error(message: string, data?: unknown): void

记录 ERROR 级别日志。

LogCat.error('请求失败', error);

tag(tag: string, level: LogLevel, message: string, data?: unknown): void

使用指定标签记录日志。

import { LogLevel } from '@/uni_modules/gp-logcat';

LogCat.tag('Network', LogLevel.INFO, '请求发送', { url: '/api' });

getState(): LogCatState

获取当前状态。

const state = LogCat.getState();
console.log(state.isInitialized); // true
console.log(state.logPath); // /storage/emulated/0/Android/data/.../logs
console.log(state.options); // 当前配置

getStatistics(): LogStatistics | null

获取日志统计信息。

const stats = LogCat.getStatistics();
if (stats) {
  console.log(stats.fileCount); // 文件数量
  console.log(stats.totalSize); // 总大小
  console.log(stats.files); // 文件列表
}

cleanOldLogs(): number

手动清理过期日志，返回清理的文件数量。

const cleaned = LogCat.cleanOldLogs();
console.log(`清理了 ${cleaned} 个过期文件`);

cleanAllLogs(): number

清理所有日志文件。

const cleaned = LogCat.cleanAllLogs();

readLog(date: string): string | null

读取指定日期的日志内容。

const content = LogCat.readLog('2024-01-15');

readTodayLog(): string | null

读取今天的日志内容。

const content = LogCat.readTodayLog();

exportLogs(dates?: string[]): string[]

导出日志文件路径。

// 导出所有日志
const allPaths = LogCat.exportLogs();

// 导出指定日期的日志
const paths = LogCat.exportLogs(['2024-01-15', '2024-01-16']);

setWriteCallback(callback: LogWriteCallback | null): void

设置日志写入回调。

LogCat.setWriteCallback((entry, success) => {
  if (!success) {
    console.log('日志写入失败:', entry);
  }
});

updateOptions(options: Partial): void

动态更新配置。

LogCat.updateOptions({ minLevel: LogLevel.WARN });

类型导出

import {
  // 枚举
  LogLevel,
  LogLevelPriority,

  // 类型
  LogEntry,
  LogCatOptions,
  LogCatState,
  LogStatistics,
  LogFileInfo,
  LogWriteCallback,
  ILogCat,
  CreateLogCatFn,

  // 实例和方法
  LogCat,
  createLogCat,
  initLogCat,
  logDebug,
  logInfo,
  logWarn,
  logError,
} from '@/uni_modules/gp-logcat';

日志文件格式

日志文件按日期命名，格式为 {prefix}_{YYYY-MM-DD}.txt。

文件内容格式：

2024-01-15 10:30:45.123 [APP][INFO] 用户登录成功 | {"userId":123}
2024-01-15 10:31:02.456 [APP][ERROR] 请求失败 | Error: Network error

注意事项

1. 该插件主要针对 Android 平台，需要使用 plus.android API
2. 在非 APP-PLUS 环境下，仅启用控制台输出功能
3. 日志文件存储在应用私有目录，卸载应用后会被删除
4. 建议在 App.vue 的 onLaunch 生命周期中初始化

平台兼容性