Nuxt4 Cookie 与客户端存储

做网站经常要「记住」一些状态，比如用户是否登录、当前选了深色还是浅色主题。这些状态存在哪、怎么存，就是本篇的内容。

什么是 Cookie

Cookie 是浏览器存的一小段键值数据，每次请求会自动带上，所以它适合存「服务端也需要知道」的信息，比如登录凭证。Nuxt 提供 useCookie 来读写，并且兼容服务端渲染。

<script setup>
// 声明一个 Cookie，名为 token
const token = useCookie('token')

// 读取
console.log(token.value)

// 写入（赋值即写入浏览器）
token.value = 'abc123'
</script>

useCookie 返回的变量是响应式的，token.value 既能读也能写。它和普通的 document.cookie 不同，Nuxt 会帮你处理 SSR 下的同步问题。

设置过期时间

默认 Cookie 在浏览器关闭后失效。可以用 maxAge 设置存活秒数。

const token = useCookie('token', {
  maxAge: 60 * 60 * 24 * 7 // 7 天
})

其他常用选项还有 path（作用路径）、secure（只在 HTTPS 下发送）、httpOnly（JS 读不到，更安全，但要在服务端设置）。

关于 httpOnly

httpOnly 的 Cookie 前端 JS 取不到，只能由服务端读取，用来防 XSS 偷凭证。本站点的登录态建议由服务端接口设置成 httpOnly。前端用 useCookie 能设置的，都不够安全，别把敏感信息放前端可读的 Cookie 里。

客户端存储 localStorage / sessionStorage

如果只是「前端自己用、服务端不需要」的数据（比如主题偏好、表单草稿），用 localStorage 或 sessionStorage 更合适。Nuxt 提供 useStorage 来跨端兼容地读写。

const theme = useStorage('theme', 'light')

// 读取
console.log(theme.value)

// 写入
theme.value = 'dark'

useStorage 在服务端渲染时不会真的写浏览器存储，避免报错。两者的区别。

• localStorage 持久保存，除非手动清除。
• sessionStorage 只在当前标签页会话内有效，关掉就没了。

一个实用例子：记住主题

结合前面的知识，深色模式可以这样持久化。

<script setup>
const theme = useStorage('theme', 'light')

function toggle() {
  theme.value = theme.value === 'light' ? 'dark' : 'light'
  document.documentElement.classList.toggle('dark', theme.value === 'dark')
}
</script>

配合 网站配置篇 里那段内联脚本，刷新页面也不会闪白。

怎么选

• 服务端也要用（如登录凭证） → Cookie（httpOnly 由服务端设）。
• 只前端用、要长期记住 → localStorage。
• 只前端用、关页面就清 → sessionStorage。
• 别在 Cookie 或前端存储里放密码、密钥等敏感信息。

记住这一点，状态该存哪就清楚了。