小程序 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.request、tt.downloadFile、tt.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
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 数据。

小程序 Cookie 机制收藏我的收藏