SvelteKit+Vite项目构建报错：localStorage未定义

算力阿峰

2026-7-9

问题：SvelteKit项目构建时出现localStorage is not defined错误

我正在开发一个基于Vite构建的SvelteKit项目，在某TypeScript文件中编写了如下代码：

let db_exists_key = "database-exists"
let db_exists = localStorage.getItem(db_exists_key)

if (db_exists != "exists") {
    await initUnitsAndDimensions()
    await initCalculator()
    localStorage.setItem(db_exists_key, "exists")
}

这段代码用于判断项目是否首次运行：

若为首次运行，则初始化数据库及其架构；
若非首次运行（数据库已存在），则不再重复初始化。

但构建时出现如下错误：

node:internal/event_target:1033
  process.nextTick(() => { throw err; });
                           ^
ReferenceError [Error]: localStorage is not defined
    at path/to/project/.svelte-kit/output/server/chunks/dimension.js:35:1
Emitted 'error' event on Worker instance at:
    at [kOnErrorMessage] (node:internal/worker:300:10)
    at [kOnMessage] (node:internal/worker:311:37)
    at MessagePort.<anonymous> (node:internal/worker:212:57)
    at [nodejs.internal.kHybridDispatch] (node:internal/event_target:757:20)
    at exports.emitMessage (node:internal/per_context/messageport:23:28)

报错路径指向的代码行是：

let db_exists = localStorage.getItem(db_exists_key);

错误提示localStorage is not defined，请问该问题的原因是什么？

原因分析

环境差异导致：localStorage是浏览器专属的API，仅存在于浏览器运行环境中，Node.js服务器环境并没有这个内置对象。
SSR执行逻辑：SvelteKit默认采用服务端渲染（SSR）模式，你的代码会先在服务器端执行一次，再在客户端执行。当代码在服务器端运行时，直接访问localStorage就会触发“未定义”的错误。
打包路径佐证：报错路径.svelte-kit/output/server/chunks/dimension.js明确显示，这段代码被打包到了服务器端执行文件中，说明代码没有做环境判断，导致服务器端执行时触发错误。