# Web Storage 参考

URL: https://caijiao.org/reference/web-api/web-storage
Source: docs/reference/web-api/web-storage.md
Description: Web Storage Reference，整理 localStorage、sessionStorage、setItem、getItem、removeItem、过期时间处理、演示和常见错误。

Web Storage 包括 `localStorage` 和 `sessionStorage`，适合保存少量字符串数据，例如用户偏好、临时表单草稿、工具输入缓存。

## 语法

```js
localStorage.setItem("key", "value");
const value = localStorage.getItem("key");
```

## localStorage 与 sessionStorage

| API | 生命周期 | 常见用途 |
| --- | --- | --- |
| `localStorage` | 手动删除前长期保留 | 主题偏好、工具配置、低敏缓存 |
| `sessionStorage` | 当前标签页会话内保留 | 临时步骤、一次性表单状态 |

## 常用方法

| 方法 | 说明 |
| --- | --- |
| `setItem(key, value)` | 写入字符串 |
| `getItem(key)` | 读取字符串，缺失时返回 `null` |
| `removeItem(key)` | 删除某个键 |
| `clear()` | 清空当前源下的全部存储 |
| `key(index)` | 按索引读取键名 |

## 示例

```js
const payload = {
  value: "dark",
  expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
};

localStorage.setItem("theme", JSON.stringify(payload));

const raw = localStorage.getItem("theme");
const item = raw ? JSON.parse(raw) : null;

if (item && item.expiresAt > Date.now()) {
  console.log(item.value);
}
```

## 可运行演示

[在线代码演示](/web-api/demos/web-storage-note.html)

## 常见错误

- Web Storage 只能保存字符串；对象要先 `JSON.stringify()`，读取后再 `JSON.parse()`。
- localStorage 没有内置过期时间，需要自己保存 `expiresAt` 并在读取时判断。
- 不要保存 token、密码、身份证号等敏感信息。
- SSR 环境没有 `window` 和 `localStorage`，要放到客户端代码中执行。

## 相关内容

- [Web API Reference](/reference/web-api/)
- [localStorage 如何设置过期时间](/how-to/javascript/localstorage-expire)
- [localStorage 和 sessionStorage 有什么区别](/how-to/javascript/sessionstorage-vs-localstorage)
- [JavaScript 教程](/javascript/)
- [MDN Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)