JavaScript localStorage基本用法:增删改查代码示例
全面讲解 JavaScript 中 localStorage 的核心概念与基本用法,提供增(setItem)、查(getItem与遍历)、改(覆写更新)、删(removeItem与clear)的完整代码示例,深入解析复杂对象 JSON 序列化存取技巧与异常防护。
一、认识 localStorage 的核心特征与存储架构
在直接调用 API 之前,先明确 localStorage 的几项核心物理规则,这有助于我们在编写代码时避免潜在的隐蔽故障:
- 同源隔离保护:存储空间严格绑定到当前网页的源(Origin),即“协议 + 域名 + 端口”必须完全一致。
http://example.com无法读取https://example.com存储的数据,不同子域名之间同样彼此隔绝。 - 持久化留存:除非用户手动清除浏览器缓存、主动调用清除代码,或者使用浏览器无痕浏览模式(关闭窗口即销毁),否则存储在
localStorage中的数据永不过期。 - 类型单一性:
localStorage的底层规范只允许存储字符串。如果直接存入数字、布尔值或普通 JavaScript 对象,浏览器会先隐式调用其toString()方法进行强转。 - 容量与同步调用:各主流浏览器为每个源分配的上限通常约为 5MB。所有 API 的读写过程均为同步阻塞(Synchronous)执行,因此不能用于存放体积极大的二进制文件或高频日志,以免阻碍主线程 UI 渲染。
二、增(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}`);
}
四、改(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() 是不可逆的破坏性操作。如果同一个网站中由不同组件或第三方 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() 反序列化还原为原生对象。
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。
八、核心 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 序列化封装后,即可在前端构建出轻量、稳定且具备离线记忆能力的交互体验。
前端JS使用CryptoJS实现AES加密的完整步骤
2026-11-18 21:43:18
JS强制刷新页面清除缓存的常用方法
2026-11-18 15:09:53
JavaScript中replaceAll与replace去除空格的性能差异
2026-11-17 23:12:34
JS DOM查询性能优化:缓存选择器结果与减少重排
2026-11-17 19:33:38
JS数组push、unshift、splice的性能差异与适用场景
2026-11-17 18:27:58








