Cookies

Cookies 对象提供了一组用于操作 HTTP Cookie 的接口。它以 name + domain + path 作为唯一键来管理 Cookie 对象集，并提供添加、获取、删除 Cookie 等功能。

构造函数

const cookies = new Cookies(cookieStr?, isSetCookie?);

参数：

方法

get

cookies.get(name?): null | Cookie | Array<Cookie>;

获取指定名称的 Cookie 对象。如果存在多个匹配的 name，则返回一个 Cookie 对象数组。

参数:

Cookie 对象

Cookie 对象表示一个 HTTP Cookie，其属性与 Set-Cookie HTTP 头部字段定义的属性一致。 以下列出了 Cookie 对象的属性，更多详细信息请参考 MDN Set-Cookie 文档:

set

cookies.set(name: string, value: string, options?: Cookie): boolean;

覆盖添加 Cookie。如果添加成功，则返回 true；如果添加失败（例如超过了 Cookie 数量限制），则返回 false。

注意： 以 name + domain + path 为唯一键，覆盖添加 Cookie。

参数：

append

cookies.append(name: string, value: string, options?: Cookie): boolean;

追加 Cookie，适用于相同 name、多个 value 的场景。如果添加成功，则返回 true；如果添加失败（例如 value 重复或超过了 Cookie 数量限制），则返回 false。

注意： 以 name + domain + path 为唯一键，追加 Cookie。

remove

cookies.remove(name: string, options?: Cookie): boolean;

删除 Cookie。

注意： 以 name + domain + path 为唯一键，删除 Cookie。

参数：

使用限制

特殊字符自动转义

• name 值中包含以下字符会被自动转义： " ( ) , / : ; < = > ? @ [ ] \ { }、0x00～0x1F、 0x7F~0xFF。
• value 值中包含以下字符会被自动转义： ,、;、"、\、0x00~0x1F、0x7F~0xFF。

Cookie 大小限制

• Cookie 属性 name 的大小不超过 64 字节。
• Cookie 属性 value、domain、path、expires、maxAge、sameSite 的累计大小不超过 1KB。
• Cookies 转义后所有字段的总长度不超过 4KB。
• Cookies 中包含的 Cookie 对象总数不超过 64 个。

示例代码

function handleEvent(event) {
  const response = new Response('hello world');

  // 创建 Cookies 对象
  const cookies = new Cookies('ssid=helloworld; expires=Sun, 10-Dec-2023 03:10:01 GMT; path=/; domain=.example.com; samesite=.example.com', true);

  // 设置响应头 Set-Cookie
  response.headers.set('Set-Cookie', cookies.toString()); 

  return response;
}

addEventListener('fetch', (event) => {    
  event.respondWith(handleEvent(event));
});

相关参考

• MDN Set-Cookie 文档