更新记录

1.0.1（2025-12-24）

• 优化安卓插件写入文件逻辑

1.0.0（2025-12-24）

• 插件初始版本

平台兼容性

uni-app(4.66)

uni-app x(4.66)

关于版本

【源码授权版】和【普通授权版】功能上是完全一样的。
【源码授权版】适用于项目对外部插件源代码有要求或者需要基于插件源码进行二次开发和定制的场景。

关于插件

本插件为uniapp提供存储日志到本地文件的功能。存储好的日志可以在APP里面查看，也可以通过HTTP上传到服务器作为用户反馈问题的日志文件，方便分析用户反馈的问题和BUG。

日志文件支持以下特性：

1. 采用原生多线程和异步队列，将日志提交和日志存储进行分离，提高日志写入的整体性能
2. 支持按天进行自动分割存储，同一天的日志会独立存储成一个日志文件
3. 支持按文件大小进行分割存储，如果同一天的日志文件超过配置的最大单文件大小(maxFileSize)时，会进行自动分割成另一个独立的文件，后缀使用数字1.2.3.4...进行标识
4. 支持旧日志自动清理，超过指定保留时间的会被删除，超过指定最大大小(maxStorageSize)的旧的文件会被删除
5. 支持读取已保存的日志文件内容

如何使用

引入

import { UtsLocalLogger, UtsLocalLoggerReader } from '@/uni_modules/ts-log-tool';

日志写入基本使用

创建全局实例

推荐使用JS模块建立全局实例，例如新建一个utils/global.js文件

import { UtsLocalLogger } from '@/uni_modules/ts-log-tool';
class Global {
    constructor() {
        // 这个localLogger需要APP全局共享，全局只保持这一个实例即可，不要重复new多个实例。因为这个日志底层是使用单实例模式实现的。
        const localLogger = new UtsLocalLogger()
        this.data = {
            localLogger: localLogger
        }
    }
    getLocalLogger() {
        return this.data.localLogger
    }
}

// 创建单例
const globalInstance = new Global()
// 导出
export default globalInstance

简单直接写入日志

不需要进行任何初始化配置，直接写入日志内容到文件中

import globalInstance from '@/utils/global.js'
const localLogger = globalInstance.getLocalLogger()

// 简单直接写入日志到本地文件
// 不需要任何配置，直接使用Logger工具默认的配置
// 直接写入日志内容到文件中，整体体验和 console.log() 基本一致
function simpleUsage() {
    // 使用log()写入日志内容
    localLogger.log("这是一个简单的测试的日志。This is a simple test log.")

    // 使用写入日志等级、日志标签、日志内容的便利方法
    localLogger.debug("订单模块", "这个是一个Debug调试日志")
    localLogger.info("用户模块", "这个是一个Info提示日志")
    localLogger.warn("商品模块", "这个是一个Warn警告日志")
    localLogger.error("支付模块", "这个是一个Error错误日志")
}

自定义配置日志

如果默认的配置不能满足你的需求，可以自定义配置

function configLogger() {
    console.log("===配置日志===", "")
    // 日志文件是支持滚动存储的，滚动机制如下：
    // （1）日志会按天进行分割存储，同一天的日志会独立存储成一个文件
    // （2）日志会按文件大小进行分割存储，如果同一天的日志文件超过配置的最大大小(maxFileSize)时，会进行自动分割成另一个独立的文件，后缀使用数字.1.2.3.4进行标识
    // （3）日志会进行自动清理：超过指定保留时间的会被删除，超过指定最大大小(maxStorageSize)的旧的文件会被删除
    localLogger.configLogger({
        logDirLocation: "Cache", // 日志文件存储位置。可选：File-存储在APP的数据目录，不会被系统自动删除；Cache-存储在APP的缓存目录，可能会被系统删除
        level: "Debug", // 日志存储到文件的日志等级。可选：Debug-调试，Info-提示，Warn-警告，Error-错误
        maxFileSize: 10 * 1024 * 1024, // 单一日志文件最大大小，单位Byte。这里配置10MB
        maxStorageSize: 100 * 1024 * 1024, // 所有日志文件最大总大小，单位Byte。这里配置100MB
        retentionDays: 7, // 日志最多保存几天。这里配置是7天，超过7天的日志文件会被删除，只留下没有超过7天的
        success: (result) => {
            console.log("成功配置日志: ", JSON.stringify(result))
        },
        fail: (errMsg) => {
            console.log("配置日志出错: ", JSON.stringify(errMsg))
            return
        },
        complete: () => {}
    })
}

自定义写入日志

如果上面直接简单写入日志方法不能满足你的要求，可以使用这个自定义写入日志的方法。也可以基于此方法封装自己需要的其他日志写入的便利方法。

// 写入日志
// 支持：日志等级、日志标签、日志内容
// 为了高性能，写入的日志是先缓存在内存中，然后再定期保存到本地文件中
function testWriteLog() {
    console.log("===测试写入日志===", "")
    let logCount = 100
    for (let idx = 0; idx < logCount; idx++) {
        let message = `这是一个测试的日志。This is a test log. ${idx}`

        // 一条日志写入最终会存储成日志文件中的一行文本，存储到文件中的文本格式如下：
        // 时间戳 [标签TAG] 日志等级 - 日志内容
        // 
        // 以下是样例：
        // 2025-12-17 09:45:33.168 [订单模块] DEBUG - 这是一个测试的日志。This is a test log. 10
        // 2025-12-17 09:45:33.175 [订单模块] INFO - 这是一个提示日志
        // 2025-12-17 09:45:33.179 [用户模块] ERROR - 这是一个错误日志
        // 2025-12-17 09:45:33.185 [商品模块] DEBUG - 这是一个调试的日志
        // 
        // 存储好的本地日志文件可以通过HTTP上传给服务器，作为分析用户遇到的问题进行诊断的依据
        localLogger.writeLog({
            level: "Debug",   //【可选项】日志等级，和上面的配置日志等级对应，默认为Debug。可选：Debug-调试，Info-提示，Warn-警告，Error-错误
            tag: '订单模块',   //【可选项】日志标签，自定义。默认为：Default
            message: message, //【必填项】日志内容。message内容末尾无需包含换行符，存到日志文件的中的时候插件会自动增加换行符
            success: (result) => {
                console.log("成功写入日志: ", JSON.stringify(result))
            },
            fail: (errMsg) => {
                console.log("写入日志出错: ", JSON.stringify(errMsg))
                return
            },
            complete: () => {}
        })
    }
    console.log("写入日志：", `${logCount} 条`)
}

关闭日志

注意：如果你关闭了日志，则必须再次手动配置后才能使用

// 这个关闭动作一般都是APP销毁的时候调用即可
// 如果不调用这个关闭理论上问题也不大，影响就是最后写入的日志可能会来不及保存到文件而丢失了
function shutdownLogger() {
    console.log("===关闭日志===", "")
    localLogger.shutdownLogger({
        success: (result) => {
            console.log("成功关闭日志: ", JSON.stringify(result))
        },
        fail: (errMsg) => {
            console.log("关闭日志出错: ", JSON.stringify(errMsg))
            return
        },
        complete: () => {}
    })
}

获取已保存的日志文件信息

这里可以获取日志的绝对路径，得到这个绝对路径，你可以使用下面的日志文件读取工具打开读取内容，也可以使用HTTP文件上传的工具上传日志文件到服务器上。

function showLogFileInfo() {
    console.log("===日志文件信息===", "")
    localLogger.getLoggerFileInfo({
        success: (result) => {
            console.log("日志文件信息: ", JSON.stringify(result))
        },
        fail: (errMsg) => {
            console.log("获取日志文件信息出错: ", JSON.stringify(errMsg))
            return
        },
        complete: () => {}
    })
}

样例：
日志文件信息: 
{
  "pathInfoList": [
    {
      "filePath": "/storage/emulated/0/Android/data/io.dcloud.HBuilder/cache/logs/AppLocalLogger.2025-12-23.1.log",
      "fileSize": 13038,
      "modifiedTime": 1766474067210
    }
  ]
}

日志读取基本使用

保存的日志文件，可以通过UtsLocalLoggerReader进行读取。

// 保存的日志文件路径需要先通过localLogger获取
import globalInstance from '@/utils/global.js'
const localLogger = globalInstance.getLocalLogger()

// 读取保存在本地的日志文件
function testLogFileRead() {
    localLogger.getLoggerFileInfo({
        success: (result) => {
            if (result['pathInfoList'].length > 0) {
                // 按文件时间排序，从大到小排序（最新的在前面）
                let fileInfo = result['pathInfoList'].sort((a, b) => b.modifiedTime - a.modifiedTime)
                // 获取本地日志文件的绝对路径，这里取最新的文件作为演示
                let filePath = fileInfo[0].filePath
                // 获取日志文件的绝对路径，开始读取日志文件内容
                readLogFileText(filePath)
            } else {
                console.log("本地没有保存的日志文件", "")
            }
        },
        fail: (errMsg) => {
            console.log("获取日志文件信息出错: ", JSON.stringify(errMsg))
            return
        },
        complete: () => { }
    })
}

// 读取指定日志文件的内容
function readLogFileText(logFilePath) {
    // 使用UtsLocalLoggerReader读取日志文件的内容
    // 这个类没有经过性能调优，读取日志的时候可能会比较慢，特别是大的日志文件
    // 推荐做法，是将日志文件上传到服务器端，然后导入到ElasticSearch之类的数据库中进行友好查看
    let logFileReader = new UtsLocalLoggerReader() // 这个类可以实例化多个，不冲突

    console.log("准备读取日志文件: ", logFilePath)
    logFileReader.open({
        filePath: logFilePath,
        success: (result) => {
            // 成功打开文件
            console.log("成功打开文件: ", logFilePath)
            console.log("文件大小（Byte字节）: ", logFileReader.getFileSize())

            // 读取日志内容
            // 每次调用read()都是接着上次读取的位置往下读，持续读取直到文件末尾
            logFileReader.read({
                lineCount: 100, // 从文件读取接下来的最多100行日志
                success: (result) => {
                    if (result.lineRead == 0) {
                        console.log("注意", "已经读到文件末尾了")
                    } else {
                        console.log("成功读取文本数据: ", result.data)
                    }

                    // 读取完成了或者不需要再读取了，则可以关闭文件
                    logFileReader.close({
                        success: (result) => {
                            console.log("成功关闭文件", "")
                        },
                        fail: (errMsg) => {
                            console.log("关闭文件错误: ", errMsg)
                        }
                    })
                },
                fail: (errMsg) => {
                    console.log("读取文件出错: ", errMsg)
                    return
                },
                complete: () => {

                }
            })
        },
        fail: (errMsg) => {
            console.log("打开文件出错: ", errMsg)
            return
        },
        complete: () => {
        }
    })
}

权限要求

安卓Android权限

需要增加以下权限

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

苹果iOS权限

没有额外的权限要求