本地存储 @fx/storage

统一的本地存储工具，支持 localStorage / sessionStorage、key 前缀隔离与 AES 加密。

通过 createStorage(opts) 工厂创建配置好的实例，prefix / usePrefix / appName / type 由闭包持有，多实例互不干扰。

安装

@fx/storage 是 monorepo 内的共享包，工作区项目直接引用：

{
  "dependencies": {
    "@fx/storage": "workspace:*"
  }
}

类型

type StorageType = "localStorage" | "sessionStorage"

interface StorageOptions {
  prefix?: string // key 基础前缀，默认 "fuxi"
  usePrefix?: boolean // 是否使用前缀，默认 true；false 时不加 prefix
  appName?: string // 应用名，默认读 VITE_APP_NAME；传 "" 不拼
  type?: StorageType // 存储引擎，默认 localStorage
}

interface StorageInstance {
  getStorage<T = unknown>(key: string, encrypt?: boolean): T | null
  setStorage(key: string, value: unknown, encrypt?: boolean): void
  removeStorage(key: string, encrypt?: boolean): void
  resolveStorageKey(key: string): string
  decrypt(encryptedValue: string): unknown
}

function createStorage(opts?: StorageOptions): StorageInstance

基本用法

明文读写，值会自动 JSON 序列化 / 反序列化。

明文读写演示

读取结果：（点击「读取」查看）

加密存储

传入 encrypt: true 时使用 AES 加密（基于 secure-ls），适合 token、密码等敏感数据。

加密读写演示

解密结果：（点击「解密读取」查看）

打开控制台查看 localStorage，密文以 fxdoc-demo_ 前缀存储。

API

createStorage(opts)

创建一个配置好的存储实例。

参数	类型	默认值	说明
prefix	string	"fuxi"	key 基础前缀
usePrefix	boolean	true	是否使用前缀；false 时不加 prefix
appName	string	读 VITE_APP_NAME	应用名，多应用隔离；传 "" 不拼
type	StorageType	"localStorage"	存储引擎

最终 key 拼接规则：[prefix]_[appName]_[key]，缺省部分自动省略。

实例方法

方法	说明
getStorage(key, encrypt?)	读取值，自动 JSON 反序列化；encrypt=true 从加密存储读取
setStorage(key, value, encrypt?)	写入值，自动 JSON 序列化；encrypt=true 加密存储
removeStorage(key, encrypt?)	移除指定 key
resolveStorageKey(key)	返回拼接前缀后的完整 key，用于 storage 事件比对
decrypt(encryptedValue)	解密一段本实例加密的密文（开发调试用）

多应用命名空间隔离

@fx/storage 默认自动读取 Vite 环境变量 VITE_APP_NAME 并拼接到 key，使每个应用的数据天然隔离。消费方只需在 .env 配置应用名，无需传参、无需 vite.config 配置、无需插件：

# .env
VITE_APP_NAME=fx-admin-web

@fx/storage 内部自动读取，最终 key 为 fuxi_fx-admin-web_{key}。新应用零代码（.env 一行即隔离）。

显式传 appName: "" 给 createStorage 可关闭拼接。

浏览器环境

@fx/storage 基于 window.localStorage，适用于 Web / H5 环境。小程序 / App 等非浏览器环境需额外适配存储引擎。