Set-Cookie

Set-Cookie HTTP 响应头用于从服务器向用户代理发送 cookie，以便用户代理稍后将其发送回服务器。要发送多个 cookie，应在同一响应中发送多个 Set-Cookie 头。

警告：根据 Fetch 规范的要求，浏览器阻止前端 JavaScript 代码访问 Set-Cookie 头，Fetch 规范将 Set-Cookie 定义为 禁止的响应头名称，必须从暴露给前端代码的任何响应中过滤掉。

当 Fetch API 或 XMLHttpRequest API 请求 使用 CORS 时，除非请求包含凭据，否则浏览器会忽略服务器响应中存在的 Set-Cookie 头。请访问 使用 Fetch API - 包含凭据 和 XMLHttpRequest 文章 以了解如何包含凭据。

有关更多信息，请参见关于 使用 HTTP cookie 的指南。

头类型 响应头
禁止的头名称 否
禁止的响应头名称 是

语法

http
Set-Cookie: <cookie-name>=<cookie-value>
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>
Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date>
Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly
Set-Cookie: <cookie-name>=<cookie-value>; Max-Age=<number>
Set-Cookie: <cookie-name>=<cookie-value>; Partitioned
Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value>
Set-Cookie: <cookie-name>=<cookie-value>; Secure

Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Strict
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Lax
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=None; Secure

// Multiple attributes are also possible, for example:
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly

属性

定义 cookie 名称及其值。cookie 定义以名称值对开头。

<cookie-name> 可以包含除以下字符之外的任何 US-ASCII 字符：控制字符（ASCII 字符 0 到 31 和 ASCII 字符 127）或分隔符（空格、制表符和以下字符：( ) < > @ , ; : \ " / [ ] ? = { }）

<cookie-value> 可以选择用双引号括起来，并包含任何 US-ASCII 字符，但不包括控制字符（ASCII 字符 0 到 31 和 ASCII 字符 127）、空白、双引号、逗号、分号和反斜杠。

编码：许多实现对 cookie 值执行 百分比编码。但是，RFC 规范不要求这样做。百分比编码确实有助于满足对 <cookie-value> 允许字符的要求。

注意：某些 <cookie-name> 具有特定语义

__Secure- 前缀：名称以 __Secure-（破折号是前缀的一部分）开头的 cookie 必须从安全页面（HTTPS）设置，并带有 secure 标志。

__Host- 前缀：名称以 __Host- 开头的 cookie 仅发送到设置它们的宿主子域或域，而不是发送到任何其他宿主。它们必须设置 secure 标志，必须来自安全页面（HTTPS），不得指定域，并且路径必须为 /。

Domain=<domain-value> 可选

定义将发送 cookie 的宿主。

只有当前域可以设置为值，或者更高阶的域可以设置为值，除非它是公共后缀。设置域将使 cookie 对其及其所有子域可用。

如果省略，此属性默认为当前文档 URL 的宿主，不包括子域。

与之前的规范相反，域名前面的点（.example.com）会被忽略。

不允许使用多个宿主/域值，但是如果确实指定了域，则始终包含子域。

Expires=<date> 可选

将 cookie 的最大生存期指示为 HTTP 日期时间戳。有关所需格式，请参阅 Date。

如果未指定，cookie 将变为 会话 cookie。会话在客户端关闭后结束，之后会删除会话 cookie。

警告：许多 Web 浏览器具有 会话恢复 功能，该功能将保存所有选项卡并在下次使用浏览器时恢复它们。会话 cookie 也将被恢复，就好像浏览器从未关闭一样。

当设置 Expires 日期时，截止日期是相对于设置 cookie 的 客户端 而言的，而不是相对于服务器而言的。

HttpOnly 可选

禁止 JavaScript 访问 cookie，例如，通过 Document.cookie 属性。请注意，使用 HttpOnly 创建的 cookie 仍然会随 JavaScript 启动的请求一起发送，例如，当调用 XMLHttpRequest.send() 或 fetch() 时。这可以减轻针对跨站点脚本 (XSS) 的攻击。

Max-Age=<number> 可选

指示 cookie 到期之前的秒数。零或负数将立即使 cookie 到期。如果同时设置了 Expires 和 Max-Age，则 Max-Age 优先。

Partitioned 可选

指示应使用分区存储来存储 cookie。有关更多详细信息，请参阅 具有独立分区状态的 Cookie (CHIPS)。

Path=<path-value> 可选

指示浏览器发送 Cookie 头时请求 URL 中必须存在的路径。

正斜杠 (/) 字符被解释为目录分隔符，并且还会匹配子目录。例如，对于 Path=/docs，

  • 请求路径 /docs、/docs/、/docs/Web/ 和 /docs/Web/HTTP 将全部匹配。
  • 请求路径 /、/docsets、/fr/docs 将不匹配。
SameSite=<samesite-value> 可选

控制 cookie 是否随跨站点请求发送，从而提供对跨站点请求伪造攻击 (CSRF) 的一定程度的保护。

可能的属性值为

严格

表示浏览器仅针对同站点请求发送 cookie，即源自设置 cookie 的同一站点的请求。如果请求源自不同的域或方案（即使具有相同的域），则不会发送带有 SameSite=Strict 属性的 cookie。

松散

表示 cookie 不会在跨站点请求中发送，例如，在加载图像或框架的请求中不会发送，但在用户从外部站点导航到源站点时会发送（例如，当跟随链接时）。如果未指定 SameSite 属性，则这是默认行为。

无

表示浏览器随跨站点请求和同站点请求一起发送 cookie。设置此值时，还必须设置 Secure 属性，例如 SameSite=None; Secure。如果缺少 Secure，则会记录错误

Cookie "myCookie" rejected because it has the "SameSite=None" attribute but is missing the "secure" attribute.

This Set-Cookie was blocked because it had the "SameSite=None" attribute but did not have the "Secure" attribute, which is required in order to use "SameSite=None".

注意：Secure cookie 仅在通过 HTTPS 协议进行加密请求时才发送到服务器。请注意，不安全的站点 (http:) 无法设置带有 Secure 指令的 cookie，因此无法使用 SameSite=None。

警告：将来版本的浏览器可能会阻止在跨站点上下文中设置了 SameSite=None; Secure 但没有设置 Partitioned 属性的 cookie。此行为保护用户数据免受跨站点跟踪。请参阅 具有独立分区状态的 Cookie (CHIPS) 和 第三方 cookie。

Secure 可选

表示仅当使用 https: 方案进行请求时才将 cookie 发送到服务器（除了在本地主机上），因此，它对 中间人 攻击更具抵抗力。

注意：不要假设 Secure 可以阻止对 cookie 中敏感信息的访问（会话密钥、登录详细信息等）。如果未设置 HttpOnly cookie 属性，则仍然可以使用对客户端硬盘的访问或从 JavaScript 来读取/修改带有此属性的 cookie。

不安全的站点 (http:) 无法设置带有 Secure 属性的 cookie（从 Chrome 52 和 Firefox 52 开始）。当本地主机设置 Secure 属性时，会忽略 https: 要求（从 Chrome 89 和 Firefox 75 开始）。

示例

会话 cookie 在客户端关闭时被删除。如果 cookie 没有指定 Expires 或 Max-Age 属性，则 cookie 为会话 cookie。

http
Set-Cookie: sessionId=38afes7a8

持久 cookie 在特定日期 (Expires) 或经过特定时间长度 (Max-Age) 后被删除，而不是在客户端关闭时被删除。

http
Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT
http
Set-Cookie: id=a3fWa; Max-Age=2592000

无效域

对于不包含设置它的服务器的域的 cookie，用户代理应拒绝。

如果由托管在 originalcompany.com 上的服务器设置，以下 cookie 将被拒绝

http
Set-Cookie: qwerty=219ffwef9w0f; Domain=somecompany.co.uk

对于服务域的子域的 cookie 将被拒绝。

如果由托管在 example.com 上的服务器设置，以下 cookie 将被拒绝

http
Set-Cookie: sessionId=e8bb43229de9; Domain=foo.example.com

仅当从安全 (HTTPS) 源设置带有 secure 属性时，才能使用以 __Secure- 或 __Host- 为前缀的 cookie 名称。

此外，带有 __Host- 前缀的 cookie 必须具有 / 的路径（表示宿主上的任何路径），并且不得具有 Domain 属性。

警告：对于没有实现 cookie 前缀的客户端，您不能依赖这些额外的保证，并且始终会接受带前缀的 cookie。

http
// Both accepted when from a secure origin (HTTPS)
Set-Cookie: __Secure-ID=123; Secure; Domain=example.com
Set-Cookie: __Host-ID=123; Secure; Path=/

// Rejected due to missing Secure attribute
Set-Cookie: __Secure-id=1

// Rejected due to the missing Path=/ attribute
Set-Cookie: __Host-id=1; Secure

// Rejected due to setting a Domain
Set-Cookie: __Host-id=1; Secure; Path=/; Domain=example.com
http
Set-Cookie: __Host-example=34d8g; SameSite=None; Secure; Path=/; Partitioned;

注意：分区 cookie 必须设置 Secure。此外，建议在设置分区 cookie 时使用 __Host 前缀，以使它们绑定到主机名而不是可注册域。

规范

规范
HTTP 状态管理机制
# sane-set-cookie

浏览器兼容性

BCD 表格只能在浏览器中加载

兼容性说明

  • 从 Chrome 52 和 Firefox 52 开始，不安全的网站 (http:) 无法再使用 Secure 属性设置 cookie。

另请参阅