useStorage：本地数据持久化利器

作者独泪了无痕

2026年2月13日 20:55

前言

一、基础概念

1.1 什么是本地存储

在Web开发中，本地存储是指将数据存储在客户端浏览器中，以便在不同的页面或会话之间保持数据的持久性。本地存储可以帮助我们存储用户的偏好设置、临时数据以及其他需要在用户关闭浏览器后仍然存在的数据。对浏览器来说，使用 Web Storage 存储键值对比存储 Cookie 方式更直观，而且容量更大，它包含两种：localStorage 和 sessionStorage

	Cookie	localStorage	sessionStorage
数据的生命期	一般由服务器生成，可设置失效时间。如果在浏览器端生成Cookie，默认是关闭浏览器后失效	除非被清除，否则永久保存，可变相设置失效时间	仅在当前会话下有效，关闭页面或浏览器后被清除
存放数据大小	4K左右	一般为5MB
与服务器端通信	每次都会携带在HTTP头中，如果使用cookie保存过多数据会带来性能问题	仅在客户端（即浏览器）中保存，不参与和服务器的通信
易用性	源生的Cookie接口不友好，需要自己封装	源生接口可以接受，亦可再次封装

1.2 useStorage 简介

useStorage 是 Vue 用于数据持久化的核心工具，它能够自动将响应式数据同步到 localStorage 或 sessionStorage 中。这个功能对于需要保存用户偏好设置、表单数据或应用状态的场景特别有用。这样，我们就可以在Vue组件中方便地使用本地存储来持久化数据，提供更好的用户体验和数据管理能力。

// hooks/useStorage.ts
/**
 * 获取传入的值的类型
 */
const getValueType = (value: any) => {
    const type = Object.prototype.toString.call(value)
    return type.slice(8, -1)
}

export const useStorage = (type: 'sessionStorage' | 'localStorage' = 'sessionStorage') => {
    /**
     * 存储数据
     * @param key
     * @param value
     */
    const setStorage = (key: string, value: any) => {
        const valueType = getValueType(value)
        window[type].setItem(key, JSON.stringify({type: valueType, value}))
    }
    /**
     * 获取某个存储数据
     * @param key
     */
    const getStorage = (key: string) => {
        const value = window[type].getItem(key)
        if (value) {
            const {value: val} = JSON.parse(value)
            return val
        } else {
            return value
        }
    }

    /**
     * 清除某个存储数据
     * @param key
     */
    const removeStorage = (key: string) => {
        window[type].removeItem(key)
    }

    /**
     * 清空所有存储数据，如果需要排除某些数据，可以传入 excludes 来排除
     * @param excludes 排除项。如：clear(['key'])，这样 key 就不会被清除
     */
    const clear = (excludes?: string[]) => {
        // 获取排除项
        const keys = Object.keys(window[type])
        const defaultExcludes = ['dynamicRouter', 'serverDynamicRouter']
        const excludesArr = excludes ? [...excludes, ...defaultExcludes] : defaultExcludes
        const excludesKeys = excludesArr ? keys.filter((key) => !excludesArr.includes(key)) : keys
        // 排除项不清除
        excludesKeys.forEach((key) => {
            window[type].removeItem(key)
        })
        // window[type].clear()
    }

    return {
        setStorage,
        getStorage,
        removeStorage,
        clear
    }
}

二、使用帮助

2.1 用法

<script setup lang="ts">
import { useStorage } from "@/hooks/useStorage";

const { setStorage, getStorage, removeStorage, clear } = useStorage();
// const { setStorage, getStorage, removeStorage, clear } = useStorage('localStorage');
</script>

useStorage 提供了四个核心函数来操作数据，如下表所示。

方法名	简要说明
setStorage	存储数据。将要用于引用的键名作为第一个参数传递，将要保存的值作为第二个参数传递。
getStorage	获取某个存储数据
removeStorage	清除某个存储数据
clear	清除所有缓存数据，如果需要排除某些数据，可以传入 excludes 来排除，如：clear(['key'])，这样 `key` 就不会被清除

2.2 储存数据

使用 setStorage 方法可以将数据进行持久化存储，例如：

<script setup lang="ts">
import {useStorage} from "@/hooks/useStorage";

const { setStorage } = useStorage();
setStorage('accessToken', 'Bearer ' + response.data.result.accessToken);
</script>

这里，accessToken是键，Bearer + response.data.result.accessToken 是对应的值。除此以外，支持非字符串类型存取值：

<script setup lang="ts">
import {useStorage} from "@/hooks/useStorage";

const { setStorage } = useStorage();
  
setStorage('key', { name: 'Jok' })
</script>

注意：由于 localStorage 操作的是字符串，如果存储的是JSON对象，需要先使用 JSON.stringify() 将其转换为字符串，取回时再使用 JSON.parse() 还原。

2.3 取出数据

获取存储的数据则使用 getStorage 方法：

<script setup lang="ts">
import {useStorage} from "@/hooks/useStorage";

const { getStorage } = useStorage();
const accessToken = getStorage('accessToken');
</script>

2.4 删除数据

如果需要移除某个键值对，可以调用 removeStorage 方法：

<script setup lang="ts">
import {useStorage} from "@/hooks/useStorage";

const { removeStorage } = useStorage();
removeStorage('key')
</script>

2.5 更改数据

要更新已存储的数据，同样使用 setStorage 方法，覆盖原有的值：

<script setup lang="ts">
import {useStorage} from "@/hooks/useStorage";

const { setStorage } = useStorage();
getStorage('accessToken', '更改后' + response.data.result.accessToken);
</script>

2.6 清除数据

<script setup lang="ts">
import {useStorage} from "@/hooks/useStorage";

const { clear } = useStorage();
clear()
</script>

三、总结

Vue 中使用 localStorage 可以方便地在用户关闭和重新打开浏览器时保持应用状态，解决像 Cookie 那样需要刷新才能获取新值的问题。合理运用 localStorage 和 sessionStorage，可以在不增加服务器负担的情况下，提供更好的用户体验。

普通视图

前言