更新记录

1.1.1（2026-09-09） 下载此版本

• 修复 iOS 云打包链接失败（Undefined symbols for architecture arm64: _mlog_*）：根因是 UTS 的 iOS 原生混编仅编译 Swift 源码，src/MSXlogBridge.mm（OC/C++ 桥接）从未参与编译，导致 Swift 侧 @_silgen_name 引用的 8 个 mlog_* C 函数符号缺失。
• 将 MSXlogBridge.mm 预编译为 arm64（iphoneos）与 x86_64（iphonesimulator）目标文件，并入 Libs/axenxlog/libaxenxlog.a，与 Mars/OpenSSL 实现合为单一自包含静态库。
• 按官方 UTS 插件 .a 库目录规范，在 Libs/axenxlog/ 中补充必须的头文件 MSXlogBridge.h。
• 验证：arm64 真机（本地离线打包全流程：插件 framework 链接 + 主工程构建 + 插件嵌入）与 DCloud 云打包（Xcode 26.2 云端环境）UTS 插件编译/链接均通过；云打包后续失败仅与签名配置相关（免费个人团队的 Xcode-managed profile 与云打包手动签名不兼容），与插件无关。
• 文档：README iOS 章节重写，说明自包含静态库结构、.mm 不参与云编译的原因与 libaxenxlog.a 重建步骤。

1.1.0（2026-08-21） 下载此版本

• 鸿蒙端新增 x86_64 模拟器 ABI（libs/x86_64/libmarsxlog.so），与 arm64-v8a 共同覆盖真机与模拟器（HarmonyOS NEXT 仅 64 位，无需 32 位 ABI）。
• 说明：iOS 维持 libaxenxlog.a（arm64 真机 + x86_64 模拟器）方案；Apple Silicon 模拟器需以 Rosetta 运行（DCloud 离线 SDK 的 UTS 基础模块暂未提供 arm64-simulator Swift 模块），待 DCloud SDK 支持后切换 xcframework。

1.0.7（2026-08-21） 下载此版本

• 新增鸿蒙 HarmonyOS 平台支持（uni-app / uni-app x）。
• 新增 utssdk/app-harmony/：UTS 入口 + XlogBridge.ets 混编桥接 + NAPI 原生桥接层 NapiXlog.cc（注入 Tencent Mars OHOS 构建，产出 libmarsxlog.so）。
• libmarsxlog.so 增加 NAPI 导出：open/write/flush/flushSync/close/setConsoleLog/setMaxFileSize/setMaxAliveTime/getLogDir/getLogFilesJson/cleanExpiredLogs，ArkTS 侧 import xlogNative from 'libmarsxlog.so' 直接调用。
• 鸿蒙默认日志目录 filesDir/xlog/logs、缓存目录 cacheDir/xlog/cache；cacheDays 默认 0（与 Android 一致，日志直接写入 logDir）。
• getLogFilesJson 同时扫描 logDir 与 cacheDir（source 区分），并过滤 mmap 缓冲文件；原生层自动创建目录并带 hilog 诊断日志（tag MarsXlogNapi）。
• 说明：鸿蒙 HAR 不支持携带 .so，使用方需将 libmarsxlog.so 放入项目 harmony-configs/entry/libs/arm64-v8a/（打包时自动打进 HAP）。
• 已在鸿蒙模拟器完成端到端验证：init → info/error → flush → getLogFilesJson → 文件落盘与列表展示。
• Android 端修复 cacheDays 不生效的问题：Xlog.open 新增带 cacheDays 的重载并真正传参，默认 0（日志直接写入 logDir）；getLogFiles/cleanExpiredLogs 改为同时扫描 logDir 与 cacheDir，与 iOS / 鸿蒙行为对齐。
• 三端 getLogFiles/getLogFilesJson 统一过滤 mmap 缓冲文件（.mmap2/.mmap3），仅返回日志文件。

平台兼容性

uni-app(3.8.3)

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（云打包 + arm64 真机 + x86_64 模拟器）、鸿蒙 HarmonyOS（NAPI + libmarsxlog.so）均已验证通过

📦 安装

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

本插件已通过自研本地验证工具完成 Android 真机 / iOS 真机与模拟器 / 鸿蒙模拟器接入验证与自测，iOS UTS 插件编译链接已在 DCloud 云打包环境（Xcode 26.2）验证通过；如有复杂接入场景，可通过插件市场作者联系方式咨询。

🚀 快速开始

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: 0,                   // 0=日志直接写入 logDir（推荐）
  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
• 鸿蒙默认缓存目录：cacheDir/xlog/cache
• 鸿蒙默认日志目录：filesDir/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 目录。三端文件列表均自动过滤 mmap 缓冲文件。

⚠️ 鸿蒙 HarmonyOS 说明

• 鸿蒙实现位于 utssdk/app-harmony/：index.uts（UTS 入口）+ XlogBridge.ets（混编 ArkTS，通过 NAPI import xlogNative from 'libmarsxlog.so' 调用原生）+ libs/{arm64-v8a,x86_64}/libmarsxlog.so（内置原生库，覆盖真机与模拟器；HarmonyOS NEXT 仅 64 位，无需 32 位 ABI）。
• cacheDays 默认 0（Android / 鸿蒙一致）：日志直接写入 logDir；getLogFiles() / getLogFilesJson() 会同时扫描 logDir 与 cacheDir（source 字段区分 logs/cache），并自动过滤 mmap 缓冲文件（.mmap2/.mmap3）。
• 若将 cacheDays 配置为 >0：日志会先写入 cacheDir（缓存保留 cacheDays 天后由 Xlog 自动移入 logDir），此时请通过 getLogFilesJson() 的 source 字段区分文件来源。
• .so 打包方式：鸿蒙的 HAR 不支持携带 .so，需要将 libmarsxlog.so 手动放入项目的 harmony-configs/entry/libs/<abi>/ 目录（HBuilderX 会把 harmony-configs 覆盖到生成的鸿蒙工程），打包时 hvigor 会自动将其打进 HAP 的对应 libs/<abi>/。arm64-v8a 用于真机、x86_64 用于模拟器；插件目录 utssdk/app-harmony/libs/ 内已附带两个 ABI 的库，直接拷贝即可。

• 原生库重建：libmarsxlog.so 由 Tencent Mars 的 OpenHarmony 构建产出，并在 libraries/mars_ohos_sdk/NapiXlog.cc 注入了 NAPI 桥接（open/write/flush/close/setMaxFileSize/setMaxAliveTime/getLogDir/getLogFilesJson/cleanExpiredLogs 等）。如需重新编译：

  cmake /path/to/mars/mars \
  -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK/native/build/cmake/ohos.toolchain.cmake \
  -DOHOS=ON -DOHOS_ARCH=arm64-v8a -DCMAKE_BUILD_TYPE=Release -G Ninja
  ninja -C build

  编译产物为 libmarsxlog.so，替换插件 utssdk/app-harmony/libs/<abi>/ 与项目 harmony-configs/entry/libs/<abi>/ 中的同名文件。当前提供 arm64-v8a（真机）与 x86_64（模拟器）两个 ABI，分别用 -DOHOS_ARCH=arm64-v8a / -DOHOS_ARCH=x86_64 编译。

• 依赖 libc++_shared.so：鸿蒙应用运行库默认已包含，无需额外配置。

⚠️ iOS 说明

• iOS 原生依赖为 utssdk/app-ios/Libs/axenxlog/libaxenxlog.a（arm64 真机 + x86_64 模拟器），库内已自包含 Mars Xlog / OpenSSL 实现与 mlog_* C 桥接层（MSXlogBridge.mm 的预编译产物），HBuilderX 云打包与自定义基座可直接使用，无需任何 OC/C++ 源码参与编译。
• Libs/axenxlog/MSXlogBridge.h 是 DCloud UTS 插件 .a 库目录规范要求的头文件，必须与 libaxenxlog.a 同目录存放，请勿删除或移动。
• 重要：UTS 的 iOS 原生混编仅编译 Swift 源码；src/MSXlogBridge.mm 与 src/mars/ 头文件仅作为重建静态库的源码保留，HBuilderX 与云打包不会编译它们。历史版本（≤1.1.0）曾误以为 .mm 会参与编译，导致云打包链接阶段 mlog_* 符号全部未定义，1.1.1 起改为预编译进库修复。
• 已完成验证：arm64 真机链接（本地离线打包全流程）、DCloud 云打包 UTS 插件编译与链接（Xcode 26.2 云端环境）、x86_64 模拟器（Rosetta）运行链路。
• Apple Silicon 模拟器需以 Rosetta 运行（DCloud 离线 SDK 的 UTS 基础模块暂未提供 arm64-simulator Swift 模块），待 DCloud SDK 支持后插件可直接切换为 xcframework。

重建 libaxenxlog.a（仅在修改 src/MSXlogBridge.mm 时需要）

cd utssdk/app-ios
SDK=$(xcrun --sdk iphoneos --show-sdk-path)
SIMSDK=$(xcrun --sdk iphonesimulator --show-sdk-path)
# 1. 编译桥接对象（arm64 真机 / x86_64 模拟器）
xcrun -sdk iphoneos clang -x objective-c++ -c src/MSXlogBridge.mm -I src \
  -target arm64-apple-ios11.0 -isysroot "$SDK" \
  -fobjc-arc -std=gnu++17 -stdlib=libc++ -O2 -o /tmp/bridge-arm64.o
xcrun -sdk iphonesimulator clang -x objective-c++ -c src/MSXlogBridge.mm -I src \
  -target x86_64-apple-ios11.0-simulator -isysroot "$SIMSDK" \
  -fobjc-arc -std=gnu++17 -stdlib=libc++ -O2 -o /tmp/bridge-x86_64.o
# 2. 并入现有库的两个架构切片（ar r 会替换同名成员，可重复执行）
mkdir -p /tmp/xlog-rebuild/arm64 /tmp/xlog-rebuild/x86_64
cp /tmp/bridge-arm64.o /tmp/xlog-rebuild/arm64/MSXlogBridge.o
cp /tmp/bridge-x86_64.o /tmp/xlog-rebuild/x86_64/MSXlogBridge.o
lipo Libs/axenxlog/libaxenxlog.a -thin arm64 -output /tmp/xlog-rebuild/arm64.a
lipo Libs/axenxlog/libaxenxlog.a -thin x86_64 -output /tmp/xlog-rebuild/x86_64.a
(cd /tmp/xlog-rebuild/arm64 && ar r ../arm64.a MSXlogBridge.o)
(cd /tmp/xlog-rebuild/x86_64 && ar r ../x86_64.a MSXlogBridge.o)
ranlib /tmp/xlog-rebuild/arm64.a /tmp/xlog-rebuild/x86_64.a
# 3. 重新合成胖库并覆盖原库
lipo -create /tmp/xlog-rebuild/arm64.a /tmp/xlog-rebuild/x86_64.a \
  -output Libs/axenxlog/libaxenxlog.a

🔐 隐私与安全

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

📄 许可证

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