JavaScript localStorage基本用法:增删改查代码示例

作者:霁月

时间:2026-11-20

浏览:380

全面讲解 JavaScript 中 localStorage 的核心概念与基本用法,提供增(setItem)、查(getItem与遍历)、改(覆写更新)、删(removeItem与clear)的完整代码示例,深入解析复杂对象 JSON 序列化存取技巧与异常防护。

文章目录
localStorage 是现代 Web 浏览器原生提供的持久化键值对存储方案。它允许前端在客户端安全保存轻量状态(如界面主题、表单未提交草稿、用户折叠偏好等),数据在用户关闭页面或重启浏览器后依然有效,且不会随每一次 HTTP 请求自动上传至服务端。本文将围绕增(写入数据)、查(读取与遍历)、改(覆写更新)、删(删除指定项与全局清空)四大核心操作,逐一给出规范、直接可运行的代码示例,并剖析对象序列化和生产环境边界处理。
JavaScript localStorage基本用法:增删改查代码示例
图 0:Web Storage 客户端持久化数据模型与运行时架构概览

一、认识 localStorage 的核心特征与存储架构

在直接调用 API 之前,先明确 localStorage 的几项核心物理规则,这有助于我们在编写代码时避免潜在的隐蔽故障:

  • 同源隔离保护:存储空间严格绑定到当前网页的源(Origin),即“协议 + 域名 + 端口”必须完全一致。http://example.com 无法读取 https://example.com 存储的数据,不同子域名之间同样彼此隔绝。
  • 持久化留存:除非用户手动清除浏览器缓存、主动调用清除代码,或者使用浏览器无痕浏览模式(关闭窗口即销毁),否则存储在 localStorage 中的数据永不过期。
  • 类型单一性:localStorage 的底层规范只允许存储字符串。如果直接存入数字、布尔值或普通 JavaScript 对象,浏览器会先隐式调用其 toString() 方法进行强转。
  • 容量与同步调用:各主流浏览器为每个源分配的上限通常约为 5MB。所有 API 的读写过程均为同步阻塞(Synchronous)执行,因此不能用于存放体积极大的二进制文件或高频日志,以免阻碍主线程 UI 渲染。
JavaScript localStorage基本用法:增删改查代码示例
图 1:localStorage 运行时架构分层与同源隔离机制

二、增(Create):向 localStorage 写入数据

向本地存储写入数据使用 localStorage.setItem(key, value) 方法。该方法接收两个参数:第一个参数为键名(Key),第二个参数为要存储的值(Value)。如果指定的键在当前域下尚不存在,则会新建该项并持久化保存。

1. 写入字符串与常见基础类型

// 1. 存入纯字符串数据
localStorage.setItem('site_name', '前端知识库');

// 2. 存入数值与布尔值(注意:存储后均会被转换为字符串)
localStorage.setItem('user_score', 98);
localStorage.setItem('auto_save_enabled', true);

console.log('数据已成功写入 localStorage');
执行机制提示
setItem() 执行成功后没有返回值(返回 undefined)。如果写入时存储空间超出了浏览器的 5MB 配额上限,会抛出 QuotaExceededError 异常。对于关键业务写入,建议在外部结合 try...catch 进行防御。

三、查(Read):读取与遍历已存数据

读取单项数据使用 localStorage.getItem(key) 方法。传入键名即可获取对应的文本值。

1. 精确获取指定键的值

// 读取已存的字符串
const siteName = localStorage.getItem('site_name');
console.log(siteName); // 输出示例: "前端知识库"

// 读取之前存入的数值和布尔值
const userScore = localStorage.getItem('user_score');
const autoSave = localStorage.getItem('auto_save_enabled');

console.log(typeof userScore, userScore); // 输出示例: string "98"
console.log(typeof autoSave, autoSave);   // 输出示例: string "true"

// 恢复原始类型
const parsedScore = Number(userScore);      // 转换为数字 98
const parsedAutoSave = autoSave === 'true'; // 转换为布尔值 true

2. 键不存在时的返回值判定

当向 getItem() 传入一个不存在的键名时,方法将严格返回 null,而不是 undefined。在进行条件判断时,应使用严谨的判空逻辑:

const notFoundVal = localStorage.getItem('unknown_key');

if (notFoundVal === null) {
  console.log('未找到目标配置,使用默认参数');
}

3. 遍历当前源下的所有存储项

当需要排查调试或批量读取所有本地存储内容时,可以利用 localStorage.length 属性与 localStorage.key(index) 索引方法配合循环:

console.log('当前存储条目总数:', localStorage.length);

// 循环遍历当前域名下的所有键值对
for (let i = 0; i < localStorage.length; i++) {
  const currentKey = localStorage.key(i);
  const currentValue = localStorage.getItem(currentKey);
  console.log(`第 ${i + 1} 项 -> [${currentKey}]: ${currentValue}`);
}
JavaScript localStorage基本用法:增删改查代码示例
图 2:localStorage 增删改查四大操作核心生命周期与返回值流转

四、改(Update):修改与覆盖已有数据

在 localStorage 的规范中,更新(改)与新增(增)共用同一个方法:setItem()。

localStorage 内部以类似 Hash Map 的唯一键名结构维护数据。当调用 setItem(key, newValue) 时,如果键名已经存在,底层会自动直接使用新的值覆盖旧的值,而不会产生重复键。

1. 修改已存键值示例

// 初始写入
localStorage.setItem('theme_mode', 'light');
console.log('当前主题:', localStorage.getItem('theme_mode')); // 输出: "light"

// 原地修改:再次调用 setItem 覆盖已有键
localStorage.setItem('theme_mode', 'dark');
console.log('更新后主题:', localStorage.getItem('theme_mode')); // 输出: "dark"

// 计数器自增修改场景
function incrementVisitCount() {
  const key = 'visit_count';
  const current = Number(localStorage.getItem(key)) || 0;
  const next = current + 1;
  localStorage.setItem(key, String(next));
  return next;
}

console.log('访问次数更新为:', incrementVisitCount());

五、删(Delete):删除单项与全局清空

删除操作分为两种应用场景:精准移除单个指定的键值对,以及一次性清空当前源下的所有存储数据。

1. 单项删除:removeItem(key)

使用 localStorage.removeItem(key) 传入目标键名即可将其彻底移除。如果传入的键名本身就不存在,该方法会安全静默处理,不会抛出任何错误:

// 删除指定项
localStorage.removeItem('auto_save_enabled');

// 验证删除结果
console.log(localStorage.getItem('auto_save_enabled')); // 输出: null

// 删除一个本就不存在的键(安全执行,不报错)
localStorage.removeItem('non_existent_key');

2. 全局清空:clear()

调用 localStorage.clear() 将立即销毁当前同源存储沙箱内的所有键值项。

// 执行全量清空
localStorage.clear();

// 验证长度已归零
console.log('清空后总条目数:', localStorage.length); // 输出: 0
生产环境谨慎调用 clear()
clear() 是不可逆的破坏性操作。如果同一个网站中由不同组件或第三方 SDK 分别维护各自的缓存数据(例如:用户信息、埋点会话、第三方编辑器状态),调用 clear() 会将所有模块的数据无差别抹除。在实际工程项目中,除非是明确的用户退出登录操作,否则应优先使用 removeItem() 按键名精准删除。

六、进阶核心:存储对象与数组(JSON 序列化与异常防御)

许多初学者在尝试存储 JavaScript 对象时,常会遇到数据失真的经典问题。理解其背后的原理并掌握规范的 JSON 存取管道,是前端开发的基本功。

1. 为什么不能直接传入 Object?

const userProfile = { id: 101, username: 'dev_alex', role: 'admin' };

// 错误做法:直接存入对象
localStorage.setItem('user_profile', userProfile);

// 读取结果
console.log(localStorage.getItem('user_profile')); // 输出: "[object Object]"

产生上述现象的原因是:setItem 强制要求字符串输入,当传入普通对象时,浏览器自动调用了 Object.prototype.toString(),结果直接被固化为没有任何数据价值的 "[object Object]" 字符串。

2. 正确做法:JSON.stringify 与 JSON.parse

存入时,必须使用 JSON.stringify() 将对象序列化为标准 JSON 字符串;取出时,使用 JSON.parse() 反序列化还原为原生对象。

JavaScript localStorage基本用法:增删改查代码示例
图 3:复杂对象与数组的 JSON 序列化存储与容错还原管道

3. 工业级封装:包含异常防御与兜底回退的工具函数

在实际项目中,用户可能手动篡改 localStorage 内容,或者数据因异常写入导致不合法的 JSON 文本。如果直接调用 JSON.parse(),程序会直接抛出 SyntaxError 导致页面脚本中断。因此,严谨的封装必须包含 try...catch:

/**
 * 健壮的 localStorage 对象存取封装模块
 */
const StorageUtil = {
  // 安全存入数据(支持任何可 JSON 序列化的数据类型)
  set(key, value) {
    try {
      const serialized = JSON.stringify(value);
      localStorage.setItem(key, serialized);
      return true;
    } catch (err) {
      console.error(`localStorage 写入 [${key}] 失败:`, err);
      return false;
    }
  },

  // 安全读取数据并反序列化,支持传入默认兜底值
  get(key, defaultValue = null) {
    try {
      const raw = localStorage.getItem(key);
      if (raw === null) {
        return defaultValue;
      }
      return JSON.parse(raw);
    } catch (err) {
      console.warn(`localStorage 解析 [${key}] 异常,返回默认值:`, err);
      return defaultValue;
    }
  },

  // 安全删除指定项
  remove(key) {
    try {
      localStorage.removeItem(key);
      return true;
    } catch (err) {
      console.error(`localStorage 删除 [${key}] 失败:`, err);
      return false;
    }
  }
};

// 使用示例:
const taskList = [
  { id: 1, text: '学习 localStorage 基本增删改查', done: true },
  { id: 2, text: '封装带异常防御的 JSON 存储工具', done: true }
];

// 1. 安全存入数组
StorageUtil.set('task_list', taskList);

// 2. 安全读取数组(带默认空数组兜底)
const savedTasks = StorageUtil.get('task_list', []);
console.log('读取到的任务数量:', savedTasks.length); // 输出: 2
console.log('首个任务名称:', savedTasks[0].text);

七、开发边界与生产环境注意事项

为了在真实项目中编写出健壮、安全的前端代码,我们需要掌握以下三大边界问题:

1. 存储容量耗尽与异常处理

当存储总量超过约 5MB 的源配额时,setItem 会抛出 QuotaExceededError。如果你的应用需要暂存较大体量的数据(如离线富文本缓存),务必在写入时捕获错误,或在容量超出时清理旧的历史缓存条目:

function safeSetItem(key, value) {
  try {
    localStorage.setItem(key, value);
  } catch (e) {
    if (e.name === 'QuotaExceededError' || e.code === 22) {
      console.warn('localStorage 存储空间已满,建议清理过期旧缓存');
    } else {
      console.error('存储发生其他未知异常:', e);
    }
  }
}

2. 监听跨标签页存储事件(storage Event)

当同一个域名在浏览器的其他标签页或窗口中修改了 localStorage 时,当前标签页的 window 会接收到 storage 事件广播。这一特性常用于跨标签页的数据同步(例如多窗口同步退出登录、主题切换):

// 监听来自其他同源窗口的存储变更广播
window.addEventListener('storage', (event) => {
  console.log('检测到存储变动:');
  console.log('变动的键名:', event.key);
  console.log('变动前的值:', event.oldValue);
  console.log('变动后的值:', event.newValue);
  console.log('触发源页面 URL:', event.url);

  // 示例:其他标签页修改了主题,本页面即刻响应更新
  if (event.key === 'theme_mode' && event.newValue) {
    document.body.setAttribute('data-theme', event.newValue);
  }
});

需要特别注意:触发 setItem 或 removeItem 的当前页面本身不会触发自己的 storage 监听器,只有同源的其他开启页面才会收到通知。

3. 安全红线:严禁存放机密与鉴权凭据

因为 localStorage 中的任何内容都可以被当前页面上运行的任何 JavaScript 脚本直接读取(包括页面引入的第三方统计代码、外部 CDN 脚本或被 XSS 漏洞注入的恶意脚本),所以绝对不要将用户的明文密码、银行卡号、或者高权限身份 JWT/Token 直接保存在 localStorage 中。防范 XSS 凭证窃取的标准做法是使用服务端带有 HttpOnly 与 SameSite 标记的安全 Cookie。

JavaScript localStorage基本用法:增删改查代码示例
图 4:localStorage 核心 API、存储性能边界、安全防范与跨标签通信全景速查矩阵

八、核心 API 汇总与对比速查

操作类型 标准方法 / 属性 主要入参 返回值 关键行为特征与注意事项
增(写入) localStorage.setItem(k, v) key: String, value: String undefined 键不存在则新建;非字符串会自动转为字符串;超额抛出异常
查(读取) localStorage.getItem(k) key: String string | null 键存在返回对应字符串;键不存在时严格返回 null
查(项数) localStorage.length 无 number 只读属性,返回当前源下的总键值对数量
查(键名) localStorage.key(index) index: Number (0 ~ length-1) string | null 根据索引位置获取键名,可用于遍历操作
改(更新) localStorage.setItem(k, v) key: String, value: String undefined 复用写入方法;键名已存在时就地覆盖旧值
删(单项) localStorage.removeItem(k) key: String undefined 移除指定键名对应的项;键不存在时安全忽略
删(全清) localStorage.clear() 无 undefined 清空当前源下的所有存储项;破坏性大,需谨慎调用

掌握 localStorage 的增删改查以及 JSON 序列化封装后,即可在前端构建出轻量、稳定且具备离线记忆能力的交互体验。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章