更新记录

1.0.0（2026-08-02）

• 首发三端原生日志 UTS 插件，公共 API 以 interface.uts 为准。
• 支持初始化/停止、上下文、用户日志写入、文件列表、过期清理、ZIP 归档。
• 新增 exportLogFiles；compressLogFiles 支持可选 exportToPublicStorage 导出副本。
• 全部 API 统一返回 { success, data, error }；导出失败使用错误码 9100006。
• 提供 uni-app 与 uni-app x 示例页；三端日志文件命名规则统一。
• 新增日志配额配置与 9100007：超限时自动回收最旧 .log，不删除显式归档。
• initLogger 支持可选自动保留期清理，并补充状态、能力、归档列表和受控读取 API。

平台兼容性

uni-app(4.87)

uni-app x(5.0)

xview-logger

xview-logger 是面向 uni-app 与 uni-app x 的三端原生日志 UTS 插件。公共 API 以 utssdk/interface.uts 为准，支持 Android、iOS、HarmonyOS；不支持 Web 或小程序，未支持端不伪造成功。

功能特性

• 生命周期日志：应用前后台切换自动写入 application 日志
• 崩溃采集：在平台实际未捕获异常回调时创建独立 crash 文件
• 用户日志：INFO / WARN / ERROR / 事件日志，支持按天或按小时滚动
• 文件管理：列出、按保留天数清理三类私有日志
• 真实 ZIP：将选定日志压缩为私有归档，可选导出副本
• 显式导出：将 application、crash、user 日志复制到用户可访问目录

日志文件命名

三端私有目录与导出副本均沿用同一套文件名规则：

其中 crash 末尾时间戳为毫秒级 epoch；user 滚动策略由 initLogger({ userLogRotation }) 决定，0 为按天，1 为按小时。

快速使用

import {
  initLogger,
  setLoggerUser,
  setLoggerTag,
  writeInfoLog,
  listLogFiles,
  compressLogFiles,
  exportLogFiles
} from '@/uni_modules/xview-logger'

const initResult = await initLogger({
  userLogRotation: 0, // 0 为按天；1 为按小时
  collectLifecycle: true,
  collectCrash: true
})
if (initResult.success && initResult.data != null) {
  console.log(initResult.data.sessionId)
}

await setLoggerUser('user-1001')
await setLoggerTag('payment')
await writeInfoLog('支付页面打开')

const listResult = await listLogFiles()
if (listResult.success && listResult.data != null) {
  const logPaths = listResult.data.map((file) => file.path)
  const archiveResult = await compressLogFiles(logPaths, 'payment-session', true)
  if (archiveResult.success && archiveResult.data != null) {
    console.log(archiveResult.data.path) // 私有 archives 路径
    console.log(archiveResult.data.exportPath) // 用户目录副本；未导出时为 null
  } else if (archiveResult.error != null) {
    console.error(archiveResult.error)
  }
}

const exportResult = await exportLogFiles({
  includeApplication: true,
  includeCrash: true,
  includeUser: true
})
if (exportResult.success && exportResult.data != null) {
  console.log(exportResult.data.exportedFiles)
}

API

全部 API 返回 Promise，始终 resolve；通过 { success, data, error } 判断结果，失败时 error 为 XviewLoggerFail。完整类型定义见 utssdk/interface.uts。

参数类型

LoggerInitOptions：

type LoggerInitOptions = {
  userLogRotation: 0 | 1 // 用户日志滚动：0 按天，1 按小时
  collectLifecycle: boolean // 是否登记应用前后台观察器
  collectCrash: boolean // 是否登记未捕获异常处理器
  maxTotalBytes?: number | null // 三类 .log 总大小上限；0/null 不限制
  maxFileBytes?: number | null // 单文件大小上限；超出后创建递增后缀文件
  maxFileCount?: number | null // 三类 .log 总数量上限
  autoCleanupRetentionDays?: number | null // 大于 0 时初始化后自动清理
  autoCleanupIncludeApplication?: boolean | null
  autoCleanupIncludeCrash?: boolean | null
  autoCleanupIncludeUser?: boolean | null
}

配额超限时，插件会先按最后修改时间删除最旧的 .log（不删除 archives）；若仍无法容纳本次写入，返回 9100007。

LoggerCleanupOptions：

type LoggerCleanupOptions = {
  retentionDays: number // 保留天数，必须 >= 0；不清理显式创建的归档
  includeApplication: boolean // 是否清理 application 日志
  includeCrash: boolean // 是否清理 crash 日志
  includeUser: boolean // 是否清理 user 日志
}

LoggerExportOptions：

type LoggerExportOptions = {
  includeApplication: boolean // 是否导出 application 日志
  includeCrash: boolean // 是否导出 crash 日志
  includeUser: boolean // 是否导出 user 日志
}

compressLogFiles 参数：

结果 data 类型

成功时 data 字段结构（success === true 且 data != null）：

LoggerInitResult：

type LoggerInitResult = {
  sessionId: string
  alreadyInitialized: boolean
  applicationLogPath: string
  userLogPath: string
}

LoggerOperationResult：

type LoggerOperationResult = {
  message: string
  timestamp: number
}

LoggerFileInfo：

type LoggerFileInfo = {
  path: string
  name: string
  kind: 0 | 1 | 2 // 0 application，1 crash，2 user
  sizeBytes: number
  createdAt: number
  updatedAt: number
}

LoggerCleanupResult：

type LoggerCleanupResult = {
  removedCount: number
  retainedCount: number
  message: string
}

LoggerArchiveInfo：

type LoggerArchiveInfo = {
  path: string
  name: string
  sourceCount: number
  sizeBytes: number
  createdAt: number
  exported: boolean
  exportPath: string | null // 未要求导出时为 null
}

LoggerExportResult：

type LoggerExportResult = {
  exportedFiles: Array<LoggerExportedFileInfo>
  message: string
}

type LoggerExportedFileInfo = {
  path: string // 用户目录副本路径
  sourcePath: string // 私有源文件路径
  name: string
  kind: 0 | 1 | 2
  sizeBytes: number
  createdAt: number
}

application 日志由生命周期观察器自动写入，固定按天滚动；用户日志按 userLogRotation 滚动。

导出目录与隐私

导出目录可被用户或其他具备权限的应用访问。日志可能包含用户标识、标签、业务参数或崩溃摘要；应仅在用户明确要求诊断材料时导出，并在上传或分享前完成脱敏。

错误码