更新记录

1.0.0（2026-08-23）

• 首版：iOS Keychain 安全键值存储，支持 uni-app 与 uni-app x

平台兼容性

uni-app(5.24)

uni-app x(5.24)

iOS Keychain 安全存储

基于 iOS Keychain 的安全键值存储（UTS 插件，全同步 API）。适用于 token、设备凭证等敏感数据。同一份源码同时支持 uni-app（vue2/vue3）与 uni-app x。

平台支持

快速上手

import { setSync, getSync, removeSync } from '@/uni_modules/hans-key-chain'

setSync({ account: 'refreshToken', value: 'your-token' })

const token = getSync({ account: 'refreshToken' })   // string | null
removeSync({ account: 'refreshToken' })              // 幂等，不存在也返回 true

uni-app x 中可使用强类型：

import { setSync, getSync, SetOptions, GetOptions } from '@/uni_modules/hans-key-chain'

const so = { account: 'refreshToken', value: 'your-token' } as SetOptions
setSync(so)

const go = { account: 'refreshToken' } as GetOptions
const token = getSync(go)

页面侧只允许从 @/uni_modules/hans-key-chain 导入。

API

全部为同步方法：

参数说明

accessible 取值

非法值自动回退默认值并输出告警日志。

使用须知

1. 卸载重装数据保留：iOS Keychain 数据在 App 卸载重装后默认仍在（设备抹除才清空）。改了 account 名后旧数据不会自动消失，需要清理时用 wipeAllSync()。
2. 空值判断用 == null：uni-app x 下返回 null；uni-app (js) 下经 UTS proxy 返回的实际是 undefined。判断一律写 == null，不要用 === null。
3. 只管理本插件写入的普通条目：读到带生物识别保护的条目时会立即失败（errCode=9013001），不会阻塞弹认证框。
4. 本插件不抛异常：失败通过返回值（false / null）表达，具体原因开日志查看。

错误码

排障

import { setLogEnabled } from '@/uni_modules/hans-key-chain'
setLogEnabled(true)

日志输出到 HBuilderX 控制台，格式 [hans-key-chain][方法名] 描述 [errCode=xxxx]。

已知边界

• 单条大值建议 ≤ 数百 KB（keychain 不适合存大数据）
• iOS 模拟器 Erase All Content 会清 keychain；「卸载重装保留」需在真机验收
• 环境要求：HBuilderX 4.25+（Swift 原生混编）