Web 新 API cookieStore 值得用吗？

# Web 新 API cookieStore 值得用吗？

## 一、传统Cookie API的三宗罪

在Web开发中操作Cookie，开发者们已经忍受了二十多年的折磨。`document.cookie`这个API的设计堪称"反人类"的典范：

第一，**API 风格过于怪异**。传统 Cookie 读写共用一个属性，读是取值、写是拼接字符串赋值。这种设计违背了最基本的编程直觉：读取用属性访问，设置也用属性赋值，但两者行为完全不同。读取返回所有cookie，设置却只会新增/修改一个。这种不对称性让无数新手开发者踩坑。

第二，**需要手动转义数据**。`document.cookie` 任何特殊字符都必须开发者自己处理转义，一旦疏忽就会出现解析异常、值截断等问题，增加了不必要的心智负担。

第三，**可选项难记、易写错**。`domain`、`expires`、`secure`等配置项需要拼接在字符串里，格式严格、记忆成本高，新手很容易因为格式不对导致 Cookie 设置不生效。

这三点共同导致实际项目里几乎没人直接裸写 `document.cookie`，都会选择封装工具库。而 `cookieStore` 的出现，本意就是解决这些痛点，让原生 API 达到工具库级别的易用性。

## 二、cookieStore 能否解决以上问题？

`cookieStore` 是近年来提出的一个新 API，旨在用现代、直观的方式操作 Cookie。它提供了类似于 `localStorage` 的 `set`、`get`、`delete` 方法，并支持通过 `change` 事件监听 Cookie 的变化。那么，它是否解决了传统 API 的三大弊病呢？

### API 风格：确实易用了

`cookieStore` 的 API 设计非常符合现代开发者的习惯：

```javascript

// 设置 cookie

await cookieStore.set('foo', "bar", { expires: Date.now() + 3600_000, path: '/' });

// 读取 cookie

const cookie = await cookieStore.get('foo');

console.log(cookie?.value); // "bar"

// 删除 cookie

await cookieStore.delete('foo');

```

不再需要拼接字符串，也不再需要手动解析，一切看起来都那么自然。从 API 风格来看，`cookieStore` 无疑是一个巨大的进步。

### 转义：仍需手动处理

遗憾的是，`cookieStore` 并没有内置数据转义的能力。所以开发者仍然需要手动调用 `encodeURIComponent`。同时，`cookieStore` 会主动检查字符串中是否包含特殊字符（如分号、逗号、空格等），如果存在则会抛出错误。这意味着我们仍然逃不掉序列化和转义的工作。

```javascript

await cookieStore.set('userName', encodeURIComponent(userName));

```

读取时也要对应地解码：

```javascript

const cookie = await cookieStore.get('userName');

const userName = cookie ? decodeURIComponent(cookie.value) : null;

```

所以，在数据转义这个场景下，`cookieStore` 并没有带来本质的改变，只是将错误从“静默失败”变成了“主动抛出”，提醒开发者需要正确处理。

### 可选项：从拼字符串变成了拼对象

`cookieStore.set` 的第三个参数是一个选项对象，包含了 `expires`（毫秒时间戳或 Date 对象）、`domain`、`path`、`sameSite`、`secure` 等属性。相比传统 API 的手工拼字符串，这无疑清晰了很多。

```javascript

await cookieStore.set('session', "token123", {

expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7天后过期

path: '/'

});

```

不过，你仍然需要记住有哪些选项可用，以及它们的含义。好在如今 TypeScript 的普及和 AI 补全工具的辅助，这个问题已经不那么严重了——当你输入 `cookieStore.set(` 时，编辑器会自动提示可用的选项，大大降低了记忆负担。

整体来看，`cookieStore` 只解决了传统 API **风格怪异**的问题，序列化和配置项的痛点并没有被彻底消灭。

## 三、cookieStore 带来了哪些新能力？

除了写法优化，`cookieStore` 也确实提供了传统 API 不具备的新能力。

最典型的就是**获取更完整的 Cookie 元信息**。传统 API 只能根据键拿到值，而 `cookieStore` 可以直接读到过期时间、路径、域、安全配置等底层信息，对需要监控、管理 Cookie 的场景更友好。

但这项能力也带来限制：**cookieStore 只能在 HTTPS 环境下使用**，本地开发如果用 HTTP 协议，会直接无法调用，这对部分开发场景不够友好。

## 四、异步设计的真相：不是为了性能

很多开发者看到`cookieStore`使用`async/await`，会产生两个误解：

### 误解1："异步意味着不会阻塞主线程？"

**事实：传统API本来就不会卡顿。**

现代浏览器的 I/O 机制并没有那么脆弱。当我们在调用 `document.cookie = ...` 时，浏览器将写入操作提交给内存缓冲区后，JS 引擎就会立刻返回并继续执行后续代码，并不会等待数据真正落盘到磁盘。

因此，即便磁盘写入速度极慢，传统同步 API 也不会造成明显的 UI 卡顿。

所以"同步API导致卡顿"是个伪命题。

### 误解2："异步API能确保写入完成？"

**事实：`cookieStore`同样不保证持久化。**

既然同步 API 已经很快，那么 `cookieStore` 的异步设计是不是为了等待磁盘写入完成，从而让开发者知道 Cookie 真正持久化了呢？答案也是否定的。`cookieStore.set` 返回的 Promise 同样在 Cookie 被存入内存后就 resolve 了，并不等待磁盘 I/O。

```javascript

await cookieStore.set({ name: "critical", value: "data" });

// 这行执行时，cookie可能还没真正写到磁盘

// 如果此时断电，数据可能丢失

```

无论是传统 API 还是 `cookieStore`，浏览器写入 Cookie 时都是**先写入内存就立即返回**，并不会等待磁盘持久化完成。所以传统同步 API 并不会造成 JS 阻塞，`cookieStore` 的异步也无法真正响应 “磁盘写入完成”。

官方把它设计成异步，主要目的是兼容 Service Worker 场景并为后续权限校验预留机制，而非提升性能或可靠性。

这就导致一个尴尬结果：`cookieStore` 的异步设计**没有带来实际能力提升**，反而是掣肘。

## 总结：cookieStore 到底值不值得用？

综合以上所有特点，我的建议是：

**cookieStore 更适合偏底层的架构、框架、工具库开发者使用**，它在元信息获取、标准化 API 上有优势，适合做底层封装。

**不建议业务开发人员直接使用 cookieStore**。它没有完全摆脱手动序列化、配置繁琐的问题，异步写法又对业务代码有侵入性，同时还受 HTTPS 限制。

对业务开发而言，**最优选择依旧是基于 document.cookie 的成熟封装库**，简单、稳定、无环境限制、API 更友好，远比直接使用原生 cookieStore 更高效。

`cookieStore` 是 Web 标准化的一次有益尝试，但在易用性层面，它尚未达到能完美替代“工具库”的高度。在未来的 Web 开发中，它或许更适合作为底层基建的基石，而非业务代码的直接工具。