js-cookie 存储 JSON 对象：自动序列化与反序列化技巧

Cookie 在浏览器底层规范中仅支持纯文本字符串存储。当开发者直接向 js-cookie 写入普通 JavaScript 对象时，往往会因隐式类型转换而生成毫无意义且无法逆转的 "[object Object]" 字符串；而在每个业务读取处手动书写 JSON.stringify 与 JSON.parse 不仅充斥重复样板代码，还会因偶发的非法格式引发运行时崩溃。本文将系统讲解 js-cookie 的转换机制，并通过官方推荐的 Cookies.withConverter() API 实现一套兼具自动序列化、容错反序列化与体积安全监控的标准化存储方案。

一、为什么直接在 js-cookie 中存取对象容易踩坑

在前端日常交互中，用户偏好设置（如界面主题、侧边栏折叠状态、表格列配置）常常以多属性的对象形式存在。由于 Cookie 会随同源 HTTP 请求自动发送至服务端，不少业务团队倾向于将这些轻量数据缓存在 Cookie 中。

然而，如果使用 js-cookie 的默认方法直接写入对象：

// 错误示例：直接将普通对象作为值写入
import Cookies from 'js-cookie';

const userConfig = { theme: 'dark', fontSize: 14 };
Cookies.set('user_config', userConfig);

// 此时读取出来的结果：
console.log(Cookies.get('user_config')); // 输出: "[object Object]"

出现这种现象的根源在于：在早期的 js-cookie 2.x 版本中，库内部曾内置了 Cookies.getJSON() 方法，并在写入时自动检测并调用 JSON.stringify。但自 js-cookie 3.0.0 正式发布起，开发团队为了保持核心库的极致轻量、避免非必要开销并回归职责边界，彻底移除了 getJSON() 方法，同时默认的写入转换器仅对值执行标准字符串转换。直接传入对象时，JavaScript 会调用 Object.prototype.toString()，导致存入浏览器的实际值变为固化的 "[object Object]"，原有字段全部丢失。

二、基础手动方案的实现与工程短板

面对 v3 版本的调整，最直接的过渡方案是在存取两端手动执行编解码：

import Cookies from 'js-cookie';

// 写入端手动序列化
const settings = { sidebar: true, notify: false };
Cookies.set('app_settings', JSON.stringify(settings), { expires: 7, path: '/' });

// 读取端手动反序列化与防御
const rawValue = Cookies.get('app_settings');
let parsedSettings = null;

if (rawValue) {
  try {
    parsedSettings = JSON.parse(rawValue);
  } catch (error) {
    // 当 Cookie 被外部篡改或历史数据为纯文本时捕获异常
    console.warn('Cookie 反序列化异常，采用回退值:', error);
    parsedSettings = null;
  }
}

这种手动方案在单一页面或实验性代码中尚可应付，但在大型前端工程中存在显著缺陷：

• 样板代码严重散落：工程中数十处读写 Cookie 的地方都需要复制 try...catch 模板，不仅代码臃肿，且只要有一处遗漏异常捕获，页面就会因 SyntaxError 发生白屏。
• 无法兼顾历史数据：若线上旧版本曾存入普通纯文本（例如旧版单一的数字或字符串标识），直接调用 JSON.parse 会直接失败，无法平滑过渡。
• 缺乏集中约束：无法在统一出口对 Cookie 长度进行计算与预警，容易无意识写入超大 JSON 导致 HTTP 请求头溢出（431 Request Header Fields Too Large）。

三、核心技巧：利用 withConverter 实现自动序列化与反序列化

针对这一痛点，js-cookie 官方提供了高阶扩展接口 Cookies.withConverter(converter)。该方法接收一个包含 read 与 write 钩子函数的对象，并返回一个全新的、隔离的 Cookies 操作实例。所有通过该实例进行的读写操作，都会经过自定义钩子的统一过滤。

1. write 钩子的设计逻辑

write(value, name) 负责拦截即将存入 Cookie 的原始数据。我们需要在此处判断 value 的实际类型：如果传入的是非空对象（包括普通 Object 和 Array），则自动调用 JSON.stringify(value)；如果是数字、布尔值或普通字符串，则保持原样，交给底层默认编码机制处理。

2. read 钩子的设计逻辑

read(value, name) 负责拦截从 document.cookie 中提取并已完成基本 URL 解码的字符串。我们需要使用 try...catch 尝试调用 JSON.parse(value)。如果解析成功，直接返回还原后的结构化对象；如果解析抛出异常（说明存入的是历史普通字符串或非 JSON 格式），则静默捕获异常并返回原字符串本身，实现 100% 向下兼容。

四、完整工程实践：封装健壮的 Cookie 存储服务

下面是一个在生产环境中开箱即用的模块封装代码（文件路径通常建议放置在 src/utils/cookieStorage.js 或 .ts）：

import Cookies from 'js-cookie';

/**
 * 创建具备自动序列化与反序列化能力的 Cookie 实例
 */
export const jsonStorage = Cookies.withConverter({
  // 写入钩子：拦截 value，输出供底层写入 Cookie 的字符串
  write: function (value, name) {
    // 处理对象与数组：自动序列化
    if (typeof value === 'object' && value !== null) {
      try {
        const stringified = JSON.stringify(value);
        
        // 关键体积监控：在开发环境下如果序列化后长度超过 2048 字节给出告警
        if (process.env.NODE_ENV !== 'production' && stringified.length > 2048) {
          console.warn(`[Cookie Warn] 写入的 Cookie "${name}" 长度达到 ${stringified.length} 字节，接近单条 4KB 极限，请谨慎存储大对象！`);
        }
        
        return stringified;
      } catch (err) {
        console.error(`[Cookie Error] 序列化 Cookie "${name}" 失败，可能存在循环引用:`, err);
        return '';
      }
    }
    
    // 基本数据类型（string, number, boolean）直接返回字符串形式
    return String(value);
  },

  // 读取钩子：拦截底层读取到的原始字符串，解析后交付给调用者
  read: function (value, name) {
    if (!value) {
      return value;
    }

    // 如果首字符明显符合 JSON 容器特征（{...} 或 [...]）则尝试反序列化
    try {
      return JSON.parse(value);
    } catch (error) {
      // 容错降级：如果不是合法 JSON 文本，平滑返回原始字符串，保证老旧数据不报错
      return value;
    }
  }
});

// 导出常用的便捷助手方法，内置默认的安全配置
export const safeCookie = {
  set(name, value, attributes = {}) {
    const defaultOptions = {
      path: '/',
      sameSite: 'Lax',
      secure: window.location.protocol === 'https:'
    };
    return jsonStorage.set(name, value, { ...defaultOptions, ...attributes });
  },

  get(name) {
    return jsonStorage.get(name);
  },

  remove(name, attributes = {}) {
    return jsonStorage.remove(name, { path: '/', ...attributes });
  }
};

调用与结果验证示例

在业务组件中直接引入 safeCookie，即可实现无感的普通读写：

import { safeCookie } from './cookieStorage';

// 1. 存储复杂对象
const userProfile = {
  id: 9527,
  username: 'developer_zhang',
  preferences: { theme: 'slate', compactView: true },
  tags: ['admin', 'editor']
};

safeCookie.set('user_profile', userProfile, { expires: 30 });

// 2. 读取验证（无需任何 JSON.parse 或 try-catch）
const profile = safeCookie.get('user_profile');

console.log(typeof profile);             // 示例控制台输出: "object"
console.log(profile.preferences.theme);  // 示例控制台输出: "slate"
console.log(Array.isArray(profile.tags));// 示例控制台输出: true

// 3. 兼容读取纯字符串 Cookie（自动降级为 string）
document.cookie = "legacy_code=alpha_release; path=/";
const legacy = safeCookie.get('legacy_code');
console.log(typeof legacy, legacy);       // 示例控制台输出: "string alpha_release"

五、JSON 存入 Cookie 的边界与安全关键细节

尽管通过 withConverter 实现了优雅的代码抽象，但在浏览器底层，Cookie 依然受到 Web 规范的严格约束。在存储结构化数据时，必须清晰识别以下边界条件：

六、方案对比与总结

在实际项目开发中，针对“结构化数据在客户端的持久化”，常见技术选型对比如下：

• 原生手动 JSON 处理：适合一次性脚本或极简演示 Demo；在生产项目中容易因代码冗余及未捕获异常引发稳定性隐患。
• 基于 withConverter 的统一封装：中大型 Web 应用的首选。调用无感、底层统一编码、防御性解析，完美契合轻量会话与跨页面共享需求。
• LocalStorage / IndexedDB：当数据体积大于 2KB 或根本无需在 HTTP 请求中发送给服务端时，应坚决使用本地存储，避免无谓占用 HTTP 报文头带宽。

通过本文介绍的 Cookies.withConverter() 技巧，我们在彻底规避 [object Object] 陷阱的同时，将数据类型转换与异常处理收拢在基础设施层。调用方无需关心序列化细节，既保持了业务代码的干净纯粹，又确保了前端存储层的健壮性与可维护性。