Nuxt 3中unstorage localStorage驱动初始化报错问题排查

这个错误不是Nuxt的bug，是没处理SSR环境差异导致的——Nuxt3是服务端渲染框架，服务端环境里不存在浏览器的localStorage对象，直接初始化localStorage驱动会在服务端执行时找不到依赖，从而抛出错误。

解决方案 #

方案一：仅在客户端初始化存储实例

修改你的存储配置文件，确保localStorage驱动只在客户端环境下创建，服务端用内存驱动兜底避免报错：

import { createStorage } from "unstorage";
import localStorageDriver from "unstorage/drivers/localstorage";
import memoryDriver from "unstorage/drivers/memory";

let storage;

// 仅在客户端初始化localStorage驱动
if (process.client) {
  storage = createStorage<string | number>({
    driver: localStorageDriver({ base: 'leads:' }),
  });
} else {
  // 服务端使用内存驱动
  storage = createStorage({
    driver: memoryDriver()
  });
}

async function hasItem(key: string) {
  return await storage.hasItem(key)
}

async function addItem(item: string | number) {
  await storage.setItem('token', item)
}

async function fetchItem(key: string) {
  return await storage.getItem(key)
}

async function deleteItem(key: string) {
  await storage.removeItem(key, { removeMeta: true })
}

async function deleteAll() {
  await storage.clear()
}

async function startWatch(key: string) {
  await storage.watch((event, key) => {
    console.log(key);
  })
}

async function stopWatch() {
  await storage.unwatch();
}

export default storage;
export { addItem, deleteAll, deleteItem, fetchItem, hasItem, startWatch, stopWatch };

方案二：使用Nuxt3内置的useStorage（更推荐）

Nuxt3已经封装了unstorage，useStorage会自动处理SSR环境，无需手动判断客户端/服务端：

// 在Pinia store或组件中直接使用
import localStorageDriver from "unstorage/drivers/localstorage";

const storage = useStorage('leads:', {}, {
  driver: localStorageDriver({ base: 'leads:' })
});

// 存token
await storage.setItem('token', yourBackendToken);
// 取token
const token = await storage.getItem('token');

如果需要存储到sessionStorage（更适合登录密钥，关闭浏览器自动清空），替换驱动即可：

import sessionStorageDriver from "unstorage/drivers/sessionstorage";

const storage = useStorage('leads:', {}, {
  driver: sessionStorageDriver({ base: 'leads:' })
});

内容的提问来源于stack exchange，提问作者Kingsley