v0.1.0 为首个可用版本 ：以
uni.setStorage系列原生 API 为唯一底层依赖、不重造存储栈，把 TTL 过期管理、key 命名规范、Promise 化、多实例隔离这些每次都要重写的重复劳动收进一套 axios 心智的 API。Web 端 22 项功能验证日志全部通过；Android
Kotlin 编译链已打通，云打包 release 编译零错误，真机用例验证待进行。
一、为什么做这个库
直接用 uni.setStorage 写业务，四件事反复发生：
- 回调风格：原生 API 是 success/fail 回调，异步编排与错误处理全靠业务手工包装
- 无过期管理：缓存写进去就是永久的，TTL 轮转要自己包时间戳、自己扫过期
- key 裸奔 ：命名无规范，
clear()一键清库会误伤框架与其他模块数据（uni-/dcloud_保留前缀冲突） - 无多实例：不同业务域的缓存共享一个扁平 key 空间，隔离全靠约定
unix-storage 把这些收敛成一套库：写过 axios 的开发者看一眼 API 就能上手；clear / 清理只作用于本命名空间；全链路强类型标注。
二、核心能力
Promise 化全量 API
uts
import { set, get } from '@/uni_modules/ux-storage'
await set('token', tokenInfo, 3600_000)
const token = await get('token') // 未命中 / 已过期返回 null，不 rejectset / get<T> / remove / clear / info / keys / clearExpired 全量 async/await，业务侧不再手写 success/fail 包装。
TTL 过期管理
record 包裹过期时间戳，读取惰性判断（Date.now() > expire 即移除并返回 null）；clearExpired() 全量扫描返回清理条数。TTL 三级回退：调用级 ttl → 实例 defaultTTL → 内置永不过期，对齐 unix-request 三级合并心智。
key 前缀命名空间
默认前缀 mx_storage:（规避 uni- / dcloud_ 平台保留前缀，非法前缀在操作期以 ERR_PARAM 拦截）；keys() 剥前缀返回原始 key；clear() 按前缀过滤后逐个移除------只清理本命名空间，不触碰其他数据。
多实例
uts
import { createStorage } from '@/uni_modules/ux-storage'
import type { StorageDefaults } from '@/uni_modules/ux-storage'
const cacheStore = createStorage({ keyPrefix: 'api_cache:', defaultTTL: 300_000 } as StorageDefaults)
await cacheStore.set('user:1', user, null) // 前缀独立，与默认实例互不可见默认实例开箱即用，configureStorage 配置全局默认；createStorage(defaults) 创建隔离实例，心智对标 axios.create。
统一可预测的错误结构
StorageError 收敛 2 类错误码（ERR_PARAM 参数 / 保留前缀拦截、ERR_NATIVE 原生失败），原生 errCode 经 nativeErrCode 原值透传不翻译，errSubject 固定 unix-storage，key
挂载关联业务原始 key------错误定位不用翻底层日志。
兼容策略
读到非本库写入格式的数据（业务直写原生 API 的存量数据）按「无过期」原样返回，不报错、不误删。
三、平台支持现状
| 平台 | 状态 |
|---|---|
| Web | ✅ 编译产物验证，22 项功能验证日志全部通过（基础存取 / TTL / 命名空间与多实例 / 全局配置 / clearExpired / 错误路径六个验证页） |
| 微信小程序 | 代码全端同构（uni.setStorage 系列全端统一），待实测 |
| Android | ✅ 云打包 release 编译零错误；真机用例验证待进行 |
| iOS / 鸿蒙 | ⏳ 代码已适配，受环境限制暂未实测（iOS 需 macOS、鸿蒙需 DevEco Studio） |
四、快速上手
bash
pnpm add @meng-xi/unix-storage
mkdir -p uni_modules && cp -R node_modules/@meng-xi/unix-storage uni_modules/ux-storage
uts
import { set, get, configureStorage } from '@/uni_modules/ux-storage'
import type { StorageDefaults, StorageError } from '@/uni_modules/ux-storage'
// 项目启动时配置一次全局默认（如 App.uvue onLaunch；null 表示沿用内置默认）
configureStorage({
keyPrefix: null, // null 沿用内置默认 'mx_storage:'
defaultTTL: null // null 永不过期
})
set('theme', 'dark', null).then(() => {
console.log('已写入')
}).catch((err) => {
const e = err as StorageError
console.log(e.code, e.errMsg)
})不想搭工程？安卓真机可直接下载体验 App ：下载体验 App（APK）------上述示例工程的云打包产物，安装后即可在真机运行全部用例。
五、文档与资源
相关链接
- 示例工程 packages/playground（首页导航 + 六个功能验证页，HBuilderX 发行 Web / 云打包验证）
- API 参考
欢迎反馈与共建：GitHub