JavaScript LocalStorage

学习浏览器本地存储 API · 难度：入门 · +10XP

JavaScript LocalStorage 客户端存储

LocalStorage 是浏览器提供的客户端持久化存储 API，属于 Web Storage 规范。数据以键值对（key-value）形式存储在用户浏览器中，没有过期时间，即使关闭浏览器、重启电脑后数据依然保留（除非用户主动清除）。存储容量通常为 5MB~10MB。

LocalStorage 核心 API

基本使用

1. 只能存储字符串，复杂类型需要 JSON 序列化
2. 同源（协议+域名+端口）共享同一份 storage
3. 不同标签页可以通过 storage 事件实现跨页面通信

// 存储字符串
localStorage.setItem("username", "张三");
localStorage.setItem("theme", "dark");
// 读取数据
const name = localStorage.getItem("username");
console.log(name); // "张三"
// 读取不存在的 key
const notExist = localStorage.getItem("notExist");
console.log(notExist); // null
// 存储对象（必须 JSON 序列化）
const user = {
  id: 1,
  name: "张三",
  preferences: { theme: "dark", language: "zh" }
};
localStorage.setItem("user", JSON.stringify(user));
// 读取并解析对象
const stored = localStorage.getItem("user");
const userObj = stored ? JSON.parse(stored) : null;
console.log(userObj.name); // "张三"
// 按索引访问
for (let i = 0; i < localStorage.length; i++) {
  const key = localStorage.key(i);
  console.log(key + " = " + localStorage.getItem(key));
}

Storage 事件与跨标签页通信

// storage 事件：当其他标签页修改 localStorage 时触发
// 注意：当前页面自身修改不会触发此事件！
window.addEventListener("storage", (event) => {
  console.log("存储变化:");
  console.log("  key:", event.key);
  console.log("  oldValue:", event.oldValue);
  console.log("  newValue:", event.newValue);
  console.log("  url:", event.url); // 触发变化的页面 URL

  // 应用：多标签页同步登录状态
  if (event.key === "auth_token" && !event.newValue) {
    console.log("用户在其他标签页已登出");
    location.href = "/login";
  }
});
// 封装 localStorage 操作工具
class StorageUtil {
  static set(key, value) {
    try {
      localStorage.setItem(key, JSON.stringify(value));
      return true;
    } catch (err) {
      console.error("存储失败:", err.message);
      return false;
    }
  }
  static get(key, fallback = null) {
    try {
      const value = localStorage.getItem(key);
      return value ? JSON.parse(value) : fallback;
    } catch (err) {
      return fallback;
    }
  }
  static remove(key) {
    localStorage.removeItem(key);
  }
  static has(key) {
    return localStorage.getItem(key) !== null;
  }
}
// 使用工具类
StorageUtil.set("settings", { theme: "dark", fontSize: 16 });
const settings = StorageUtil.get("settings", { theme: "light" });
console.log(settings.theme); // "dark"

LocalStorage 限制与替代方案

// 1. 容量检测
function getStorageUsage() {
  let total = 0;
  for (let i = 0; i < localStorage.length; i++) {
    const key = localStorage.key(i);
    total += key.length + localStorage.getItem(key).length;
  }
  return (total / 1024).toFixed(2) + " KB";
}

// 2. sessionStorage：仅当前标签页有效，关闭标签页即清除
// 用法与 localStorage 完全一致
sessionStorage.setItem("temp", "临时数据");
// 3. IndexedDB：适合大量结构化数据（异步 API）
// 4. Cache API：适合离线缓存 HTTP 请求/响应
// 5. Cookies：适合需要发送到服务器的数据（每次请求都携带）
// localStorage 使用建议：
// - 存储用户偏好设置（主题、语言等）
// - 缓存不频繁变化的 API 数据
// - 存储用户草稿或表单临时数据
// - 慎用：不要存储敏感信息（明文存储，可被用户查看）