开发
API

小程序 Cookie 机制

基础库 2.45.0 开始支持 Cookie 机制。

功能介绍

字节小程序支持服务端在 tt.request 的响应中,使用 HTTP 首部中的 Set-Cookie 字段设置 Cookie。框架侧负责 Cookie 解析、存储、匹配和发送,处理逻辑遵循 RFC6265 规范。小程序之间、小程序与宿主 Cookie 相互隔离,同时支持手动设置 Cookie。

使用说明

1. 修改小程序配置项

在 app.json 中开启/关闭 Cookie 机制。

{
  "cookie": {
    "enableStore": true // true 开启小程序 Cookie 机制。默认 false
  }
}

如果需要通过服务端下发 Cookie 数据,开发者应在服务端应按照 RFC 规范设置 HTTP 首部部的 Set-Cookie 字段。只有 tt.requesttt.downloadFilett.uploadFile数据预取 发起的 HTTP 请求才会解析 Set-Cookie 字段,将 Cookie 保持到本地。

3. 客户端请求服务端资源

开发者使用 API 请求服务端,框架按照 RFC 标准自动添加对应的 Cookie。支持自动添加 Cookie 的接口见下表:

接口

说明

最低支持版本

tt.request

网络 API

2.45.0

tt.downloadFile

网络 API

2.45.0

tt.uploadFile

网络 API

2.45.0

数据预取

性能优化

2.45.0

video

视频组件

2.45.0

audio

音频 API

2.45.0

live-player

直播组件

2.45.0

tt.previewImage

图片预览 API

2.45.0

也可以在请求中设置自定义 Cookie,框架自动与本地 Cookie 合并后发送,Cookie 冲突时优先使用传入的值。示例:

  • 使用 tt.request 请求 https://developer.toutiao.com/api,服务端返回的 HTTP 首部为: HTTP/1.1 200 OK Content-Type: application/json;charset=utf-8 Set-Cookie: name1=value1 Set-Cookie: name2=value2
  • 再次使用 tt.request 请求 https://developer.toutiao.com/api,实际发送的 HTTP 首部为: GET /api HTTP/1.1 Host: developer.toutiao.com Cookie: name1=value1; name2=value2
  • 再次使用 tt.request 请求 https://developer.toutiao.com/api,同时附带参数 header: {"Cookie": "name1=value3"}。实际发送的 HTTP 首部为: GET /api HTTP/1.1 Host: developer.toutiao.com Cookie: name1=value3; name2=value2

Bug & Tip

  • Tip: 每个小程序存储的 Cookie 总数最多 1000 个,同一域名下最多 50 个。超过限制框架根据 LRU 删除旧数据;
  • Tip: 服务端每次下发 Set-Cookie 总长度不能超过 4 KB。超过限制 Set-Cookie 无效;
  • Tip: 宿主账号切换会清空 Cookie 数据。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助