更新记录

1.0.0（2026-03-18）

• 支持 iOS Keychain 安全存储
• 支持 Android Keystore + 应用私有密文存储
• 提供 set/get/remove/has/clear 能力
• 提供平台能力查询
• 支持 iOS surviveReinstall 持久保留模式
• 提供示例页面与基础文档

平台兼容性

uni-app(4.75)

uni-app x(4.75)

austin-secure-storage

austin-secure-storage 是一个面向 Android / iOS App 的安全存储插件。

它的目标不是替代 uni.setStorage，而是给敏感数据提供更合适的保存层：

• refreshToken
• 设备绑定凭证
• 本地私钥材料
• 风控标记
• 需要长期保存但不适合放普通缓存的数据

当前实现

• iOS 使用 Keychain
• Android 使用 Android Keystore 管理主密钥，并将密文保存在应用私有 SharedPreferences
• 非 App 平台直接返回不支持

点击试用插件

当前目录下的 index.vue 是完整测试页，项目里也提供了路由页面：

• pages/secure-storage/index

平衡型默认策略

建议业务分层：

• accessToken：内存
• refreshToken：安全存储
• deviceSecret：安全存储
• 昵称 / 头像 / 草稿 / 主题 / 列表缓存：uni.setStorage

也就是说：

• uni.setStorage 负责普通缓存
• austin-secure-storage 负责敏感凭证

和 uni.setStorage 的区别

两者使用上都像 set / get，但安全边界不同。

uni.setStorage 主要依赖：

• App 沙盒隔离

austin-secure-storage 的设计目标是：

• iOS 走 Keychain
• Android 走 Keystore + 应用私有密文
• 即使本地文件被拿到，也不等于直接拿到敏感值

默认卸载 / 重装策略

默认策略：

• reset_on_reinstall

原因：

• Android 卸载后通常会清空
• iOS Keychain 可能会在重装后残留
• 默认做重装检测并清理旧条目，更容易保证两端行为一致

补充：

• iOS 默认条目会在重装后被自动清理
• 如果写入时显式传 surviveReinstall: true，则条目保存到独立的 persistent service，不会被默认重装清理逻辑删掉
• Android 侧 surviveReinstall 不生效，因为卸载后应用数据本来就会删除

适合的使用场景

• 登录态恢复
• 设备绑定
• 企业 App 本地凭证保存
• 金融、医疗、会员系统的敏感凭证存储

V1 API

setSecureItem(key, value, options?)

写入安全条目。

options：

• surviveReinstall

surviveReinstall：

• 默认 false
• iOS 设为 true 时允许同设备重装后继续读取
• Android 不支持该能力，能力查询会返回 supportsSurviveReinstall = false

getSecureItem(key)

读取安全条目。

未命中时建议返回：

• ok = true
• found = false

removeSecureItem(key)

删除指定条目。

hasSecureItem(key)

判断条目是否存在。

clearSecureItems()

清空插件管理的安全条目。

getSecureStorageCapabilities()

获取当前平台能力与实现状态。

最小调用

import {
  setSecureItem,
  getSecureItem,
  removeSecureItem,
  hasSecureItem,
  clearSecureItems,
  getSecureStorageCapabilities,
} from '@/uni_modules/austin-secure-storage'

const capabilities = getSecureStorageCapabilities()
console.log('secure-capabilities', capabilities)

const setRet = setSecureItem('refresh_token', 'token_xxx')
console.log('setRet', setRet)

const getRet = getSecureItem('refresh_token')
console.log('getRet', getRet)

const hasRet = hasSecureItem('refresh_token')
console.log('hasRet', hasRet)

const removeRet = removeSecureItem('refresh_token')
console.log('removeRet', removeRet)

const clearRet = clearSecureItems()
console.log('clearRet', clearRet)

业务流程示例

1. 登录成功后拿到 refreshToken
2. 调 setSecureItem('refresh_token', token)
3. App 冷启动时调用 getSecureItem('refresh_token')
4. 如果 found=true，就去服务端刷新登录态
5. 用户退出登录时调用 removeSecureItem('refresh_token')

说明

• 如果业务想在读取前加一道人脸 / 指纹锁，可以在业务层先做验证
• 当前版本只面向字符串值，复杂对象请业务层自行 JSON.stringify
• Android 依赖 Keystore 的 AES 能力，建议在 Android 6.0 / API 23 及以上使用