localStorage 工具

不会抛错的 localStorage 访问，以及建立在它之上的带前缀 JSON 视图。

localStorage 不只是在 SSR 下不存在：在禁用 cookie 的三方 iframe 里连访问都会抛错， Safari 隐私模式和配额用尽时写入也会抛错。这里每一次读写都有保护，因为存储失败该降级的是一项偏好设置，而不是整个页面。

API

localStorageSetItem

设置 localStorage 中的值。

Parameters

参数	说明	类型	默认值
`name`	键名	`string`	无
`value`	值	`string`	无

Return

无返回值（void）

localStorageGetItem

获取 localStorage 中的值。

Parameters

参数	说明	类型	默认值
`name`	键名	`string`	无

Return

参数	说明	类型
`string`	存储的值，如果不存在返回空字符串	`string`

localStorageRemoveItem

删除某个键。

参数	说明	类型	默认值
`name`	键名	`string`	无

createStore(prefix?)

建立在 localStorage 之上的、带前缀并自动 JSON 序列化的视图。

返回值

方法	说明
`get(key, fallback)`	读取值；不存在、不可用或解析失败时返回 `fallback`
`set(key, value)`	序列化后写入；未写成功时返回 `false`
`remove(key)`	删除该键
`keyOf(key)`	完整存储键（`prefix + key`），监听 `storage` 事件时有用

Example

基础用法

import { localStorageSetItem, localStorageGetItem } from 'ranuts';

// 设置值
localStorageSetItem('username', 'john');

// 获取值
const username = localStorageGetItem('username');
console.log(username); // 'john'

存储对象

import { localStorageSetItem, localStorageGetItem } from 'ranuts';

const user = { name: 'John', age: 30 };
localStorageSetItem('user', JSON.stringify(user));

const storedUser = JSON.parse(localStorageGetItem('user'));
console.log(storedUser); // { name: 'John', age: 30 }

服务端安全

import { localStorageSetItem, localStorageGetItem } from 'ranuts';

// 在服务端环境中不会报错，会静默失败
localStorageSetItem('key', 'value'); // 服务端环境：无操作
const value = localStorageGetItem('key'); // 服务端环境：返回 ''

检查是否存在

import { localStorageGetItem } from 'ranuts';

const value = localStorageGetItem('myKey');
if (value) {
  console.log('值存在:', value);
} else {
  console.log('值不存在');
}

带命名空间的 JSON 存储

import { createStore } from 'ranuts';

const history = createStore('agent_history_');

history.set('default', messages); // 写入 agent_history_default
const restored = history.get('default', []); // 不存在或损坏时返回 []
history.remove('default');

同一个源下的多个功能

import { createStore } from 'ranuts';

// 前缀让互不相关的功能不会撞键。
const keys = createStore('agent_api_key_');
const prefs = createStore('editor_prefs_');

keys.set('anthropic', token);
prefs.set('theme', 'dark');

注意事项

这里没有任何一处会抛错。存储不存在、三方 iframe 被禁、隐私模式、配额用尽，全部静默降级：localStorageGetItem 返回 ''，写入函数什么也不做，createStore().set() 返回 false。
在调用时判断，而不是模块加载时。存储对象在每次调用内部才去取，因此 SSR 后再水合的流程同样正确，测试里也可以替换。
createStore 不做校验。存进去什么就按 T 取出来什么；跨版本时请自行检查。兜底值只覆盖「不存在」和「解析失败」两种情况：老版本代码写入的值不会把 SyntaxError 抛给调用方，但它的结构仍然可能是错的。
set 返回 false 的情况：循环引用、BigInt、以及写入没有真正落盘。它会把值读回来确认。
类型限制：底层两个函数只处理字符串。需要存对象时用 createStore，不要在每个调用点手写 JSON.stringify / JSON.parse 加 try/catch。
返回值：localStorageGetItem 在值不存在时返回 '' 而不是 null。