更新记录

1.0.5（2026-06-22）

• 修复 iOS 标准 UTS 调试链路下 axen-uts-xlog 插件编译失败的问题。
• 调整 iOS 原生依赖结构：合并 Mars Xlog 与 OpenSSL 为 Libs/axenxlog/libaxenxlog.a，并保留 x86_64 模拟器与 arm64 真机 slice。
• 修正 iOS Objective-C++ 桥接源位置：MSXlogBridge.h/mm 与 Mars 头文件放入 utssdk/app-ios/src/，确保 HBuilderX 生成 target 时参与编译。
• 补齐 iOS 系统链接依赖：Security.framework、CFNetwork.framework、libc++.tbd、libz.tbd、libresolv.tbd。
• 新增 getLogFilesJson()，用于 iOS/JS 侧稳定获取日志文件列表，避免数组对象桥接时字段丢失。
• Android 端同步补齐 getLogFilesJson() 导出，统一双端日志文件 JSON 获取方式。
• iOS 文件列表扫描同时覆盖 Documents/xlog/logs 与 Library/Caches/xlog/cache，可查看已落盘日志和当前 mmap 缓存文件。

1.0.4（2026-06-16）

• 更新文档

1.0.3（2026-06-16）

• 开放源码授权版。

平台兼容性

uni-app(3.8.0)

uni-app x(4.0)

MS-Xlog 高性能日志 - uni-app 本地日志插件

基于 Tencent Mars Xlog 的 uni-app UTS 插件，为 App 提供高性能、低损耗的本地日志能力。

✨ 特性

• 🚀 高性能：基于 Mars Xlog/MMAP 的异步写入，降低主线程影响
• 📦 自动压缩：日志以 Xlog 二进制格式压缩存储
• 🔒 加密支持：可选 RSA 公钥加密日志（未传 pubKey 时不加密）
• 📂 文件管理：查看日志文件列表、清理过期日志
• 🏷️ 级别过滤：支持 VERBOSE / DEBUG / INFO / WARN / ERROR / FATAL
• 📱 双端支持：Android 真机与 iOS 标准 UTS 自定义基座链路均已验证通过

📦 安装

插件市场搜索 MS-Xlog 或直接导入 uni_modules/axen-uts-xlog。

本插件已通过自研本地验证工具完成 Android/iOS 接入验证与自测；如有复杂接入场景，可通过插件市场作者联系方式咨询。

🚀 快速开始

import {
  init, info, error, flush, getLogDir, getLogFiles, getLogFilesJson,
  XLOG_INFO
} from '@/uni_modules/axen-uts-xlog'

const res = init({
  level: XLOG_INFO,
  namePrefix: 'myapp',
  console: false,                 // 生产环境建议保持 false
  cacheDays: 7,
  maxFileSize: 5 * 1024 * 1024,
  maxAliveTime: 24 * 60 * 60,
  // pubKey: '...',               // 可选：传入后启用 Xlog 加密
})

if (res.success) {
  console.log('Xlog 日志目录:', getLogDir())
}

info('Home', '用户进入首页')
error('Pay', '支付失败: ' + JSON.stringify({ code: 1 }))
flush()

const files = getLogFiles()
files.forEach(f => console.log(f.name, f.size))

// iOS/JS 侧推荐使用 JSON 版本，避免数组对象桥接字段丢失
const fileList = JSON.parse(getLogFilesJson())

📖 API 文档

init(config?) / initXlog(config?)

初始化 Xlog，必须先调用。推荐统一使用 init；iOS 标准 UTS 运行时已提供 s_initByJs 兼容别名，内部转发到 initXlog，避免 Swift init 关键字冲突。

返回值 XlogResult：

{ success: boolean, code: number, message: string, data?: UTSJSONObject }

日志写入

verbose(tag, msg)
debug(tag, msg)
info(tag, msg)
warn(tag, msg)
error(tag, msg)
fatal(tag, msg)
log(level, tag, msg)

管理操作

flush()                        // 强制刷盘（异步）
close()                        // 关闭 Xlog
getLogDir()                    // 获取日志目录路径
getLogFiles()                  // 获取日志文件列表
getLogFilesJson()              // 获取日志文件列表 JSON 字符串，iOS/JS 侧推荐使用
setMaxFileSize(bytes)          // 设置单个日志文件最大字节数
setMaxAliveTime(seconds)       // 设置单个日志文件最长存活秒数
cleanExpiredLogs(days)         // 清理 days 天前的日志，返回删除数量

📁 日志存储位置

• Android 默认缓存目录：filesDir/xlog/cache
• Android 默认日志目录：externalFilesDir/xlog/logs
• iOS 默认缓存目录：Library/Caches/xlog/cache
• iOS 默认日志目录：Documents/xlog/logs

getLogFiles() / getLogFilesJson() 返回字段：

{
  name: string
  path: string
  source?: 'logs' | 'cache'
  size: number
  lastModified: number
}

其中 iOS 会同时扫描 Documents/xlog/logs 与 Library/Caches/xlog/cache；刚写入的活跃日志可能先出现在 cache 目录中，flush 后再落到 logs 目录。

⚠️ iOS 说明

• iOS 原生实现位于 utssdk/app-ios/，依赖 Libs/axenxlog/libaxenxlog.a、src/MSXlogBridge.h/mm、src/mars/... 头文件与系统库。
• iOS 标准 UTS 自定义基座链路已在 xlog-demo 中完成验证：init → info/error → flush → getLogFilesJson → 沙箱文件存在。
• iOS 标准链路不依赖 JS patch fallback；uniapp-launcher 当前使用 uni_modules.framework 聚合插件产物。
• 当前 iOS 静态库包含 arm64 真机与 x86_64 模拟器 slice；Apple Silicon 模拟器如需原生 arm64-simulator，可后续升级为 .xcframework。

🔐 隐私与安全

本插件只在本地写入日志文件，不主动采集 IDFA、定位、相机、麦克风、相册、通讯录信息，也不主动上传日志。日志内容由业务方传入，可能包含个人信息或敏感数据；请在业务侧避免写入 token、密码、身份证号等敏感内容，生产环境关闭 console，必要时配置 pubKey 加密。

📄 许可证

插件基于 Tencent Mars Xlog（MIT License）。第三方许可见 THIRD_PARTY_LICENSES.md；插件本体授权以插件市场页面/购买协议为准。