边缘开发者平台
  • 边缘函数
    • 概述
    • 快速指引
    • 操作指引
      • 函数管理
      • 触发配置
    • Runtime APIs
      • addEventListener
      • Cache
      • Cookies
      • Encoding
      • Fetch
      • FetchEvent
      • Headers
      • Request
      • Response
      • Streams
        • ReadableStream
        • ReadableStreamBYOBReader
        • ReadableStreamDefaultReader
        • TransformStream
        • WritableStream
        • WritableStreamDefaultWriter
      • Web Crypto
      • Web standards
      • Images
        • ImageProperties
    • 示例函数
      • 返回 HTML 页面
      • 返回 JSON
      • Fetch 远程资源
      • 请求头鉴权
      • 修改响应头
      • AB 测试
      • 设置 Cookie
      • 基于请求区域重定向
      • Cache API 使用
      • 缓存 POST 请求
      • 流式响应
      • 合并资源流式响应
      • 防篡改校验
      • m3u8 改写与鉴权
      • 图片自适应缩放
      • 图片自适应 WebP
      • 自定义 Referer 限制规则
      • 远程鉴权
      • HMAC 数字签名
      • 自定义下载文件名
      • 获取客户端 IP
    • 最佳实践
      • 通过边缘函数实现自适应图片格式转换
Docs Overview/
边缘开发者平台/
边缘函数/
Runtime APIs/
Cookies/

Cookies

Cookies 提供了一组 cookie 操作接口。
注意：
Cookies 对象以 name + domain + path 为唯一 key, 管理 Cookie 对象集。

构造函数

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

参数

参数名称
类型
必填
说明
cookieStr
string
否
Cookie 字符串或者 Set-Cookie 字符串。
isSetCookie
boolean
否
参数 cookieStr 是否是 Set-Cookie 字符串，默认为 false。

方法

get

cookies.get(name?: string): null | Cookie | Array<Cookie>;
获取指定名称的 Cookie 对象。存在多个 name 匹配时，返回 Cookie 数组。

参数

参数名称
类型
必填
说明
name
string
否
Cookie 名称，取值说明如下。
缺省 name
表示获取所有 Cookie 对象。
指定 name
表示获取指定 name 的 Cookie 对象，存在多个匹配时，返回 Cookie 数组。
Cookie 对象属性如下，详细参见 MDN 官方文档 Set-Cookie。
属性名
类型
只读
说明
name
string
是
Cookie 名称。
value
string
是
Cookie 值。
domain
string
是
Cookie 的作用域名。
path
string
是
Cookie 的作用路径。
expires
string
是
Cookie 最长有效时间, 取值符合 HTTP Date 首部标准。
max_age
string
是
Cookie 经过 max_age 秒失效，单位秒（s）。
samesite
string
是
控制 Cookie 跨站点请求伪造攻击（CSRF）的保护。
httponly
boolean
是
禁止 JavaScript 访问 Cookie，仅限 HTTP 请求携带。
secure
boolean
是
Cookie 仅限 HTTPS 请求协议携带。

set

cookies.set(name: string, value: string, options?: Cookie): boolean;
覆盖添加 Cookie。返回 true，表示添加成功，返回 false，表示添加失败（超过了 cookies 数量限制，详细参见 cookies 大小限制）。
注意：
以 name + domain + path 为唯一 key，覆盖添加 Cookie。

参数

参数名称
类型
必填
说明
name
string
是
Cookie 名称。
value
string
是
Cookie 值。
Cookie
string
否
Cookie 属性配置项。

append

cookies.append(name: string, value: string, options?: Cookie): boolean;
追加 Cookie，用于相同 name, 多个 value 的场景。返回 true，表示添加成功，返回 false，表示添加失败（value 重复或超过了 cookies 数量限制，详细参见 cookies 大小限制）。
注意：
以 name + domain + path 为唯一 key 追加 Cookie。

remove

cookies.remove(name: string, options?: Cookie): boolean;
删除 Cookie。
注意：
以 name + domain + path 为唯一 key 删除 Cookie。

参数

参数名称
类型
必填
说明
name
string
是
Cookie 名称。
options
是
Cookie 属性配置项，其中属性 domian 和 path 可支持 *, 表示匹配所有。

使用限制

特殊字符自动转义

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

cookies 大小限制

Cookie 属性 name 大小不超过 64B。
Cookie 属性 value, domain, path, expires, max_age, 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=.tencentcloud.com; samesite=.tencentcloud.com', true);

  // 设置响应头 Set-Cookie
  response.setCookies(cookies);

  return response;
}

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

相关参考

MDN 官方文档：Set-Cookie
示例函数：AB测试
示例函数：设置 Cookie