Skip to content

Cookies

Nuxt为读取和写入cookies提供了一套针对服务端渲染友好的组合式api

使用

在你的页面、组件或者是插件中,针对一条特定的cookie记录,可以使用useCookie创建一条响应式的引用。

js
const cookie = useCookie(name, options)

👉useCookie只在setupLifecycle Hooks中有效

😌useCookie ref将自动转义cookie的值成JSON格式。

示例

下面的例子创建了一条称为counter的cookie记录。如果这条cookie记录不存在,那么在初始化这条记录时可以把它设置成一个任意值。无论何时当我们更新了counter变量的值的时候,这条cookie记录也会相应的自动更新。

html
<template>
  <div>
    <h1> Counter: {{ counter || '-' }}</h1>
    <button @click="counter = null">
      reset
    </button>
    <button @click="counter--">
      -
    </button>
    <button @click="counter++">
      +
    </button>
  </div>
</template>

<script setup>
const counter = useCookie('counter')
counter.value = counter.value || Math.round(Math.random() * 1000)
</script>

注意

示例报错reading 'default',需要 const counter = useCookie('counter', { default: ()=>0 })

StackBlitz打开

配置项

组合式Cookie接受几个配置项来让你修改cookie的行为。

大部分配置项是直接引用的 cookie 包中的内容。

maxAge / expires

maxAge 明确规定了响应头中Set-CookieMax-Age属性值,该属性接收number类型,单位秒。默认不设置最大超时时间。

expires:明确规定了响应头中Set-CookieExpires属性值,该属性接收Date类型。默认不设置该值。 大部分客户端将它视为“持久化的cookie”,只在例如退出web浏览器应用程序时才会删除cookie。

💡注意: cookie的存储模型规定如果同时设置了expiresmaxAge,以maxAge优先。但是并不是所有的客户端都遵守这一规定,所以同时设置时应该让他们都指向相同的日期和时间!

如果都不社会expiresmaxAge,那么cookie将仅用于会话,当用户关闭浏览器的时候被移除。

httpOnly

明确规定了响应头中Set-CookieHttpOnly属性值,该属性接收boolean类型。当httpOnly为“真值” 时HttpOnly属性被设置,反之不设置。默认HttpOnly属性不设置。

💡注意: 小心当该值被设置成true时,合格的客户端是不允许用户侧通过javaScript脚本的方式查看documnet.cookie

secure

明确规定了响应头中Set-CookieSecure属性值,该属性接受boolean类型。当secure设置为true时,Secure被设置,反之不设置。默认Secure不设置。

💡注意: 小心当该值被设置成true时,如果当浏览器和服务器没有建立https连接,合格的客户端将不会传输cookie。这可能会导致错误。

domain

明确规定了响应头中Set-CookieDomain属性值。默认domain不设置,大部分客户端认为cookie仅适用于当前域。

path

明确规定了响应头中Set-CookiePath属性值。默认值为“default path”。

sameSite

明确规定了响应头中Set-CookieSameSite属性值

  • trueSameSite属性值设为Strict,以严格执行同站请求。
  • false不设置SameSite属性。
  • 'lax' 将SameSite属性值设为Lax,允许部分第三方请求携带 Cookie
  • 'none'允许跨站发送Cookie
  • 'strict'将SameSite属性值设为Strict,以严格执行同站请求。

关于不同实施级别的更多信息可以在 规范 中查阅。

encode

指定cookie值的编码函数。因为cookie的值是一个有限的字符集(必须是一个简单的字符串),所以该函数需要将值编码为适合cookie的字符串。

默认编码方式是 JSON.stringify + encodeURIComponent

decode

指定cookie值的解码函数。因为cookie值为一个有限的字符集(必须是一串简单的字符串),该函数需要将编码的cookie值解码成javaScript中的字符串或对象类型。

默认解码函数是 decodeURIComponent + destr .

💡注意: 如果在该函数抛出异常,那么原始的未经解码的cookie值将会作为value值返回。

API路由中处理cookies

你可以使用h3包中的useCookiesetCookie在访问服务器的API路由时候处理cookie的值。

示例:

js
import { useCookie, setCookie } from 'h3'

export default (req, res) => {
  // Read counter cookie
  let counter = useCookie(req, 'counter') || 0

  // Increase counter cookie by 1
  setCookie(res, 'counter', ++counter)

  // Send JSON response
  return { counter }
}