为什么我在 NextJs 项目中使用 cookie 存储 token 而不是使用 localstorage

Moment2025-06-10 15:26

在构建现代 Web 应用时，身份验证（Authentication） 是几乎每个项目都需要处理的重要功能。当用户登录成功后，服务器通常会返回一个 Token（如 JWT），客户端需要将它保存下来，并在后续请求中用于验证身份。

常见的两种存储方式是：

  • localStorage：浏览器本地持久化存储，开发者最常用的方式之一

  • Cookie：浏览器内置的请求头机制，可配置多个安全策略

我在最开始使用 Next.js 构建项目时，和很多人一样优先选择了 localStorage。但随着对 Next.js（尤其是 App Router 架构）理解的加深，我逐渐发现：localStorage 根本不适合存 Token，最终我全面转向了 使用 Cookie 来存储身份凭证。

在接下来的内容当中，我们将从原理、安全、框架兼容性等角度全面剖析我的这个选择。

Next.js 项目的运行环境：不仅仅是浏览器

Next.js 是一个混合型应用框架，它不仅支持传统的客户端渲染（CSR），还广泛使用：

  • 服务端组件（Server Components）

  • 中间件（middleware.ts）

  • Edge Function（边缘运行环境）

  • API Routes / Server Actions

  • 静态生成（SSG）、服务端渲染（SSR）

这意味着你的项目运行环境不仅包括浏览器（客户端），还包含 Node.js、Edge Runtime 等 无浏览器 API 的环境。

为什么 localStorage 不适合 Next.js 项目？

虽然 localStorage 在前端框架中常被用于临时存储 token，但在 Next.js 项目中，它存在以下硬伤：

1. 无法在服务端访问

Next.js 的服务端组件（Server Component）、Server Action、Edge Function 中无法访问浏览器的 localStorage，因为它们运行在服务端或边缘节点，而 localStorage 是浏览器环境独有的 API。

tsx 复制代码 
// app/profile/page.tsx - Server Component 中
export default function ProfilePage() {
  const token = localStorage.getItem("token"); // ❌ 报错：localStorage is not defined
}

2. 中间件中无法读取 localStorage

middleware.ts 是基于 Edge Runtime 执行的，也无法访问任何浏览器 API，包括 localStorage。如果你想基于 token 做权限路由控制，就完全不能依赖 localStorage。

ts 复制代码 
// middleware.ts
export function middleware(request: NextRequest) {
  const token = localStorage.getItem("token"); // ❌ Edge 环境下不可能存在
}

3. 暴露在客户端，容易被 XSS 攻击

localStorage 是开放的，所有脚本都可以访问。一旦页面存在 XSS 漏洞，token 会直接被窃取，造成严重安全风险。

为什么我选择使用 Cookie？

相较于 localStorage，Cookie 是浏览器原生支持的机制，它在 Next.js 中具备更强的兼容性和安全性：

Next.js 提供了 cookies() API，可在 服务端组件、Server Action、API Route、Middleware 等多个环境中访问 Cookie。

tsx 复制代码 
// app/dashboard/page.tsx
import { cookies } from "next/headers";

export default function DashboardPage() {
  const token = cookies().get("token")?.value;

  if (!token) {
    // 重定向或提示登录
  }

  return <div>欢迎回来！</div>;
}

浏览器会自动把 Cookie 附带到每次同源请求中：

  • 页面加载时自动发送给 SSR 服务
  • 请求 /api/xxx 时自动带上 Cookie
  • 服务端可以直接读取，不依赖前端注入

这让身份验证逻辑天然融合到请求流程中，不需要你手动设置任何请求头。

设置 HttpOnly 后，JavaScript 无法访问 Cookie，从而彻底解决 XSS 窃取 Token 的风险。

ts 复制代码 
res.cookies.set("token", token, {
  httpOnly: true,
  secure: true,
  maxAge: 3600,
  path: "/",
});

中间件是页面加载前的"守门员"，只支持 Cookie：

ts 复制代码 
// middleware.ts
import { NextRequest, NextResponse } from "next/server";

export function middleware(request: NextRequest) {
  const token = request.cookies.get("token")?.value;

  if (!token) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  return NextResponse.next();
}

你可以精准拦截未登录用户、限制特定路由访问权限。

举个例子：登录/登出流程（App Router）

接下来我们将使用一个登录/登出的例子来讲解一下 Cookie 在 NextJs项目中的应用。

ts 复制代码 
// app/api/login/route.ts
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const body = await request.json();
  const token = await verifyUserAndGenerateToken(body);

  const response = NextResponse.json({ success: true });

  response.cookies.set("token", token, {
    httpOnly: true,
    path: "/",
    maxAge: 60 * 60 * 24,
  });

  return response;
}

服务端组件中读取 token

tsx 复制代码 
// app/dashboard/page.tsx
import { cookies } from "next/headers";
import { redirect } from "next/navigation";

export default function DashboardPage() {
  const token = cookies().get("token")?.value;

  if (!token) {
    redirect("/login");
  }

  return <div>用户中心</div>;
}

middleware 权限拦截

ts 复制代码 
// middleware.ts
import { NextRequest, NextResponse } from "next/server";

export function middleware(request: NextRequest) {
  const token = request.cookies.get("token")?.value;

  const isProtected = request.nextUrl.pathname.startsWith("/dashboard");
  if (isProtected && !token) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  return NextResponse.next();
}
ts 复制代码 
// app/api/logout/route.ts
import { NextResponse } from "next/server";

export async function POST() {
  const response = NextResponse.json({ success: true });

  response.cookies.set("token", "", {
    maxAge: 0,
    path: "/",
  });

  return response;
}

总结

在 App Router 架构下，Next.js 已不再是一个纯前端框架，而是一个真正的全栈应用平台。因此，Token 的存储方式也必须适应全栈环境的特性。

Cookie，作为浏览器与服务端之间天然的桥梁，是目前在 Next.js 项目中存储 Token 最合理、最安全、最兼容的方式。

如果你还在用 localStorage 存 token，是时候升级你的身份认证方案了。

功能/特性 Cookie ✅ localStorage ❌
SSR / RSC 可访问 ✅ cookies() 可用 ❌ 无法在服务端读取
middleware 可访问 ✅ request.cookies 可用 ❌ 不存在 localStorage
自动附加请求 ✅ 默认随请求发送 ❌ 需手动加到 headers
可设置 HttpOnly ✅ 防止 XSS ❌ 直接暴露给 JS
安全性 ✅ 高，可配置 Secure/SameSite ❌ 容易被 XSS 攻击
易用性（在 App Router） ✅ 与新架构天然兼容 ❌ 基本不可用
相关推荐
Carlos_sam26 分钟前
Opnelayers：ol-wind之Field 类属性和方法详解
前端·javascript
小毛驴85036 分钟前
创建 Vue 项目的 4 种主流方式
前端·javascript·vue.js
誰能久伴不乏1 小时前
Linux如何执行系统调用及高效执行系统调用：深入浅出的解析
java·服务器·前端
涔溪2 小时前
响应式前端设计：CSS 自适应布局与字体大小的最佳实践
前端·css
今禾2 小时前
前端开发中的Mock技术：深入理解vite-plugin-mock
前端·react.js·vite
你这个年龄怎么睡得着的2 小时前
Babel AST 魔法：Vite 插件如何让你的 try...catch 不再“裸奔”？
前端·javascript·vite
我想说一句2 小时前
掘金移动端React开发实践：从布局到样式优化的完整指南
前端·react.js·前端框架
jqq6662 小时前
Vue3脚手架实现（九、渲染typescript配置）
前端
码间舞2 小时前
Zustand 与 useSyncExternalStore：现代 React 状态管理的极简之道
前端·react.js
Dream耀3 小时前
提升React移动端开发效率：Vant组件库
前端·javascript·前端框架
热门推荐
01Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code02全球最强模型Grok4，国内已可免费使用！（附教程）03vue数据变化但页面不变04KGG转MP3工具|非KGM文件|解密音频05扣子开源本地部署教程 丨Coze智能体小白喂饭级指南06干翻 Typora！MilkUp：完全免费的桌面端 Markdown 编辑器！07【2025.7.18】更新vscode后所有.vue文件template标签后报红的临时解决办法，Vue - Official 插件3.0.2导致08ChatGPT Agent 完全使用指南：2025年7月最新功能详解09《魔兽世界》提示lua警告的含义及解决方法10这次领先Cursor！体验了Trae 2.0 SOLO 模式，超酷！