sveltekit 默认启用服务端渲染（ssr），而 localstorage 是浏览器专属 api，在服务端环境中未定义，直接调用会导致构建失败。本文详解如何安全检测运行环境、条件执行 localstorage 操作，并提供类型安全与最佳实践方案。
sveltekit 默认启用服务端渲染（ssr），而 localstorage 是浏览器专属 api，在服务端环境中未定义，直接调用会导致构建失败。本文详解如何安全检测运行环境、条件执行 localstorage 操作，并提供类型安全与最佳实践方案。
在 SvelteKit（基于 Vite）项目中，当你在 .ts 或 .svelte 文件中直接调用 localStorage.getItem() 时，Vite 在构建阶段会同时生成服务端（server）和客户端（client）代码。由于服务端运行于 Node.js 环境，全局对象 window 和其属性 localStorage 均不存在，因此触发 ReferenceError: localStorage is not defined —— 这正是你遇到的错误根源。
✅ 正确做法：始终在浏览器上下文中访问 localStorage
✅ 推荐方案一：使用 $app/environment 的 browser 标志（SvelteKit 官方推荐）
import { browser } from '$app/environment';
if (browser) {
const db_exists_key = 'database-exists';
const db_exists = localStorage.getItem(db_exists_key);
if (db_exists !== 'exists') {
await initUnitsAndDimensions();
await initCalculator();
localStorage.setItem(db_exists_key, 'exists');
}
}
✅ 优势：$app/environment.browser 是 SvelteKit 提供的编译时静态标识符（在 SSR 阶段被内联为 false），零运行时开销，类型安全（boolean），且语义清晰。
✅ 推荐方案二：typeof window !== 'undefined'（通用兼容写法）
if (typeof window !== 'undefined') {
const db_exists_key = 'database-exists';
const db_exists = localStorage.getItem(db_exists_key);
if (db_exists !== 'exists') {
await initUnitsAndDimensions();
await initCalculator();
localStorage.setItem(db_exists_key, 'exists');
}
}
⚠️ 注意：此方式在 SSR 时仍会执行判断逻辑（虽不报错），但不如 browser 标志高效；适用于需兼容非 SvelteKit 环境的场景。
❌ 错误示例（禁止！）
// ❌ 构建失败：SSR 时直接执行，localStorage 未定义
const db_exists = localStorage.getItem('database-exists');
// ❌ 危险：仅在 onMount 中使用，但初始化逻辑可能被跳过（如页面直出/SEO 场景）
import { onMount } from 'svelte';
onMount(() => {
// 此处才访问 localStorage —— 但 initUnitsAndDimensions() 等异步初始化若依赖服务端数据，可能造成状态不一致
});
? 类型增强建议（可选）
为避免 TypeScript 在服务端误判 localStorage 类型，可在 src/app.d.ts 中补充环境声明（非必需，但更严谨）：
/// <reference types="@sveltejs/kit"></reference>
declare global {
interface Window {
localStorage: Storage;
}
}
export {};
? 总结与最佳实践
- 根本原则：所有浏览器专属 API（localStorage、sessionStorage、document、navigator 等）必须在客户端环境显式保护；
- 首选方案：使用 $app/environment.browser —— 官方支持、零成本、类型安全；
- 避免副作用前置：不要将带副作用的初始化逻辑（如数据库初始化）放在服务端可执行路径中；
- 进阶替代：若需持久化状态且兼顾 SSR 兼容性，可考虑结合 +page.server.ts 的 load 函数 + cookie 或服务端缓存，再通过 data 传入客户端；
- 调试提示：可通过 console.log({ browser, window: typeof window }) 快速验证当前执行环境。
遵循以上模式，你的 SvelteKit 项目即可安全、稳定地使用 localStorage，彻底规避构建时报错问题。
