Cookie 类

函数	用途	SSR 安全	响应式
useCookie	读写 Cookie	✅	✅
refreshCookie	刷新 Cookie 值	✅	N/A

useCookie

SSR 安全的 Cookie 读写，返回响应式 Ref。

// 读取 Cookie
const token = useCookie('auth-token')
console.log(token.value)  // 'my-token-value'

// 写入 Cookie
token.value = 'new-token'

// 删除 Cookie
token.value = null
// 或
token.value = undefined

// 带选项
const session = useCookie('session', {
  maxAge: 60 * 60 * 24 * 7,  // 7 天（秒）
  path: '/',
  domain: '.example.com',
  secure: true,              // 仅 HTTPS
  httpOnly: true,             // 仅服务端可写，JS 不可读
  sameSite: 'lax',           // 'lax' | 'strict' | 'none'
  encode: encodeURIComponent,
  decode: decodeURIComponent,
  default: () => ({}),       // 默认值
  watch: true,               // 响应式监听
  readonly: false,            // 只读
  refresh: false,             // v4.4+: 自动刷新过期时间
})

Cookie 选项

选项	类型	说明
maxAge	number	最大存活时间（秒）
expires	Date	过期时间
path	string	路径（默认 /）
domain	string	域名
secure	boolean	仅 HTTPS 传输
httpOnly	boolean	仅服务端可访问（防 XSS）
sameSite	'lax'|'strict'|'none'	SameSite 策略（防 CSRF）
default	() => T	默认值工厂
watch	boolean | 'shallow'	监听 Cookie 变化
readonly	boolean	只读模式
refresh	boolean	v4.4+: 每次赋值延长过期时间

安全推荐

• 认证 Token：httpOnly: true + secure: true + sameSite: 'lax'
• 用户偏好：无特殊安全要求
• CSRF Token：sameSite: 'strict'

refresh 选项（v4.4+）

每次设置值时自动延长 Cookie 过期时间（滑动会话）：

const session = useCookie('session-id', {
  maxAge: 60 * 60,     // 1 小时
  refresh: true,       // 每次赋值延长过期时间
})

// 即使值没变，赋值也会延长过期时间
session.value = session.value

适用场景

用户每次操作时延长会话过期时间（如"记住我 7 天"）。

refreshCookie

从浏览器刷新 Cookie 值（当 Cookie 被外部修改时，如服务端 API）。

// 刷新单个 Cookie
refreshCookie('auth-token')

// 刷新多个 Cookie
refreshCookie(['auth-token', 'session-id'])

何时需要 refreshCookie？

服务端 API 通过 setCookie 修改了 Cookie 后，客户端的 useCookie ref 不会自动更新。调用 refreshCookie 从浏览器读取最新值。

TIP

典型场景：登录/登出后刷新认证 Token