1. 项目背景与技术选型为什么是这三件套最近在做一个带用户体系的业务系统需要完整的注册、登录、鉴权功能。技术栈上我直接选了 Next.js 15 MySQL NextAuth.js这个组合在当下的 React 全栈生态里属于比较主流的方案。Next.js 15 的 App Router 和 Server Actions 已经相当成熟MySQL 作为关系型数据库稳定可靠NextAuth.js 则是 Next.js 官方推荐的认证库三者配合能快速搭建一套基于 Cookie/Session 的鉴权体系。先说为什么不用 JWT 而用 Session。JWT 无状态、前端直接存 token看起来方便但遇到用户被禁用了怎么办token 怎么主动失效刷新 token 如何处理这类需求时就比较头疼。Session 模式把会话状态存在服务端Redis 或数据库客户端只保存一个 session cookie服务端随时可以作废会话控制力强得多。对于需要后台管理、用户权限变更这类业务Session 是更稳妥的选择。这套方案适合谁如果你正在做 Next.js 全栈项目需要一个开箱即用、可扩展的登录注册系统或者你想从手工写 Session 中间件里解放出来这篇实战笔记应该能帮你少走不少弯路。我会把从数据库设计到 NextAuth 配置再到中间件保护路由的完整链路写清楚。2. 环境准备与数据库设计2.1 初始化 Next.js 15 项目我用的还是 create-next-app 那一套但有几个参数值得说一下。Next.js 15 默认使用 App Router所以不需要再加--app标记。我习惯加上--tailwind和--typescript前者做样式后者保证类型安全。npx create-next-applatest nextjs-mysql-auth --typescript --tailwind --eslint cd nextjs-mysql-auth项目初始化完成后顺手装依赖npm install mysql2 next-auth bcryptjs npm install -D types/bcryptjs这里注意MySQL 驱动我用的mysql2而不是老牌的mysql原因是 mysql2 支持 Promise 接口配合 async/await 写起来更清爽而且性能比 mysql 好。bcryptjs 是纯 JavaScript 实现的密码哈希库不需要编译原生模块在服务器环境比如 Vercel 的 serverless 函数上也能直接跑这点很关键——有些项目用 bcrypt 原生库部署到 serverless 平台经常遇到 node-gyp 编译问题。2.2 MySQL 数据库与用户表结构MySQL 安装我默认你已经搞定了无论是 Docker 起的还是本机装的都行。Docker 方式最快docker run --name mysql-auth -e MYSQL_ROOT_PASSWORDyourpassword -e MYSQL_DATABASEauth_demo -p 3306:3306 -d mysql:8.0用户表设计上我踩过不少坑最终稳定使用的结构是这样CREATE DATABASE IF NOT EXISTS auth_demo DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE auth_demo; CREATE TABLE users ( id INT AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE, password_hash VARCHAR(255) NOT NULL, name VARCHAR(100) DEFAULT , role ENUM(user, admin) DEFAULT user, is_active TINYINT(1) DEFAULT 1, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_email (email), INDEX idx_role (role) ) ENGINEInnoDB;几个字段设计的细节值得展开password_hash长度设置 255是因为 bcrypt 生成的哈希字符串长度通常为 60但预留一些空间防止未来算法升级。is_active字段用于用户禁用/启用这在 Session 模式下很实用管理员禁用用户后即使对方已有 session下次请求时在中间件里也能拦截。role字段用 ENUM 类型简单直接能避免应用层传入非法角色值。如果需要更灵活的角色权限体系可以拆成 roles 表和 user_roles 关联表但小项目没必要过度设计。所有 varchar 字段统一用 utf8mb4 编码。别用老旧的 utf8mb3emoji 和生僻字会直接出错。2.3 数据库连接池的封装Next.js 的 serverless 环境下每个请求都可能触发一个新的函数实例如果每次都新建 MySQL 连接连接数很容易被打满。正确的做法是使用连接池并且在全局复用。我在lib/db.ts里这样封装import mysql from mysql2/promise; const pool mysql.createPool({ host: process.env.DB_HOST || localhost, user: process.env.DB_USER || root, password: process.env.DB_PASSWORD || , database: process.env.DB_NAME || auth_demo, waitForConnections: true, connectionLimit: 10, queueLimit: 0, charset: utf8mb4, dateStrings: true, }); export default pool;这里有个需要特别留意的点不要把这个 pool 直接用在每个页面的顶层创建上。Next.js 开发模式下热更新会导致模块重新执行如果每次执行都创建新连接池内存会不断泄漏。我用了一个全局变量来缓存连接池import mysql from mysql2/promise; declare global { var _mysqlPool: mysql.Pool | undefined; } const pool global._mysqlPool || mysql.createPool({ // ...配置 }); if (process.env.NODE_ENV ! production) { global._mysqlPool pool; } export default pool;说实话这个坑我第一次遇到时排查了很久。开发环境跑着跑着内存飙升请求越来越慢最后发现是连接池被反复创建。加上全局缓存之后问题彻底解决。3. NextAuth.js 集成与 Credentials 登录配置3.1 NextAuth 的 Session 策略选择NextAuth.js现在叫 Auth.js默认支持 JWT Session 和 Database Session 两种模式。我们标题里明确了要用 Cookie/Session 鉴权所以选择 Database Session。两种方式的区别在于JWT Session 下session 数据加密后塞进 cookie服务端不存任何状态Database Session 下session 数据落在数据库的 sessions 表里cookie 里只保存一个随机的 session token。在app/api/auth/[...nextauth]/route.ts里写第一个版本import NextAuth from next-auth; import CredentialsProvider from next-auth/providers/credentials; import type { NextAuthOptions } from next-auth; import { queryUserByEmail } from /lib/auth-helper; import bcrypt from bcryptjs; export const authOptions: NextAuthOptions { session: { strategy: database, maxAge: 60 * 60 * 24 * 7, // 7天 updateAge: 60 * 60 * 24, // 每24小时更新一次session }, providers: [ CredentialsProvider({ name: credentials, credentials: { email: { label: 邮箱, type: email }, password: { label: 密码, type: password }, }, async authorize(credentials) { if (!credentials?.email || !credentials?.password) { return null; } const user await queryUserByEmail(credentials.email); if (!user) { return null; } const isValid await bcrypt.compare(credentials.password, user.password_hash); if (!isValid) { return null; } if (!user.is_active) { throw new Error(该账号已被禁用); } return { id: String(user.id), email: user.email, name: user.name, role: user.role, }; }, }), ], callbacks: { async session({ session, user }) { if (session.user) { session.user.id user.id; session.user.role user.role; } return session; }, }, pages: { signIn: /login, }, secret: process.env.NEXTAUTH_SECRET, }; const handler NextAuth(authOptions); export { handler as GET, handler as POST };看到这里你可能有个疑问为什么strategy: database时authorize里返回的对象会被自动持久化到数据库这是 NextAuth.js 的底层实现逻辑——Credentials 登录成功后系统会自动在 Session 表中创建一条记录并把返回的 user 对象存进去同时生成一个 session token 写入 cookie。你不需要手动操作数据库但前提是 Session 表必须存在。3.2 创建 NextAuth 所需的 Session 表使用 Database Session 模式NextAuth 官方要求你手动建表。官方文档里的标准 SQL 可以直接用但针对 MySQL 我做了些调整CREATE TABLE IF NOT EXISTS sessions ( id VARCHAR(255) PRIMARY KEY, session_token VARCHAR(255) NOT NULL UNIQUE, user_id VARCHAR(255) NOT NULL, expires TIMESTAMP NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_user_id (user_id), INDEX idx_expires (expires), CONSTRAINT fk_session_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这个表结构有个关键点user_id 和 users 表的主键类型必须匹配。如果你 users 表的主键是INT AUTO_INCREMENT而 sessions 表的 user_id 是 VARCHAR外键约束虽然能存但 JOIN 查询时会有隐式类型转换性能会受影响。我一开始 users 表用 INTNextAuth 文档示例里 user_id 却是 VARCHAR造成的后果是外键关联设置失败后来统一改成 VARCHAR 才解决。这里提供另一个思路你也可以不建外键约束。因为 NextAuth 处理用户删除时并不会主动清理对应的 sessions 记录外键约束反而可能导致删除用户时报错。我现在更倾向于不设置物理外键在应用层保证数据一致性删除用户时手动执行DELETE FROM sessions WHERE user_id ?。MySQL 对物理外键的性能影响争议也不少小项目用逻辑关联就够了。3.3 Credentials Provider 的注册、登录实现authorize 函数里用到了queryUserByEmail这个函数写在lib/auth-helper.ts里import pool from /lib/db; export async function queryUserByEmail(email: string) { const [rows] await pool.execute( SELECT id, email, password_hash, name, role, is_active FROM users WHERE email ? LIMIT 1, [email] ); const users rows as any[]; return users.length 0 ? users[0] : null; } export async function createUser(email: string, passwordHash: string, name: string) { const [result] await pool.execute( INSERT INTO users (email, password_hash, name) VALUES (?, ?, ?), [email, passwordHash, name] ); return (result as any).insertId; }这里务必使用参数化查询pool.execute带?占位符不要用字符串拼接 SQL。SQL 注入攻击在鉴权接口上的危害是致命的这是红线。注册接口我写在app/api/register/route.tsimport { NextResponse } from next/server; import bcrypt from bcryptjs; import { createUser, queryUserByEmail } from /lib/auth-helper; export async function POST(req: Request) { try { const body await req.json(); const { email, password, name } body; if (!email || !password || password.length 8) { return NextResponse.json( { error: 邮箱、密码至少8位为必填项 }, { status: 400 } ); } const existing await queryUserByEmail(email); if (existing) { return NextResponse.json({ error: 该邮箱已注册 }, { status: 409 }); } const passwordHash await bcrypt.hash(password, 12); const userId await createUser(email, passwordHash, name || ); return NextResponse.json({ id: userId, email }, { status: 201 }); } catch (error) { console.error(注册失败:, error); return NextResponse.json({ error: 注册失败请稍后重试 }, { status: 500 }); } }bcrypt 的 salt rounds 我用的 12。rounds 越大哈希计算越慢暴力破解成本越高但也不能无限大否则登录接口会慢得离谱。12 在当前硬件条件下大约耗时 200-300ms安全性和性能的平衡点。3.4 登录页面与服务端登录动作前端登录页我用 Server Action 配合signIn函数这样能直接使用 NextAuth 内置的登录逻辑还不用额外写客户端状态管理库。use server; import { signIn } from /auth; import { AuthError } from next-auth; export async function authenticate( prevState: string | undefined, formData: FormData ) { try { await signIn(credentials, { email: formData.get(email), password: formData.get(password), redirectTo: /dashboard, }); } catch (error) { if (error instanceof AuthError) { switch (error.type) { case CredentialsSignin: return 邮箱或密码错误; default: return 登录失败请稍后重试; } } throw error; } }登录页面组件app/login/page.tsxuse client; import { useActionState } from react; import { authenticate } from ./actions; export default function LoginPage() { const [errorMessage, formAction, isPending] useActionState( authenticate, undefined ); return ( form action{formAction} div label htmlForemail邮箱/label input idemail nameemail typeemail required / /div div label htmlForpassword密码/label input idpassword namepassword typepassword required / /div {errorMessage p style{{ color: red }}{errorMessage}/p} button typesubmit disabled{isPending} {isPending ? 登录中... : 登录} /button /form ); }Next.js 15 的useActionState取代了之前的useFormState我在一开始写的时候还习惯用旧 API结果直接报错。升级到 15 之后注意 React 19 的 Hook 名称变化。4. Cookie/Session 鉴权流程实战4.1 中间件保护路由Multer 时代后的 Next.js 中间件鉴权最关键的一环是路由保护。Next.js 的中间件middleware.ts运行在边缘环境能在请求到达页面之前拦截做 cookie 校验。NextAuth 提供了内置的withAuth中间件包装器。在项目根目录创建middleware.tsimport { withAuth } from next-auth/middleware; import { NextResponse } from next/server; export default withAuth( function middleware(req) { const token req.nextauth.token; const isAdminRoute req.nextUrl.pathname.startsWith(/admin); if (isAdminRoute token?.role ! admin) { return NextResponse.redirect(new URL(/dashboard, req.url)); } return NextResponse.next(); }, { pages: { signIn: /login, }, callbacks: { authorized: ({ token }) { // 未登录用户 token 为 null返回 false 会触发 signIn 页面跳转 return !!token; }, }, } ); export const config { matcher: [ /dashboard/:path*, /admin/:path*, /profile/:path*, ], };注意当你使用 database session 策略时中间件里的req.nextauth.token是不存在的。withAuth的中间件默认依赖 JWT 策略下的 token。要么你把中间件保护改成调用getToken并配合数据库查询要么接受中间件只负责是否有 session cookie这个粗粒度校验真正的用户信息在页面里用getServerSession拿。这个点我实际开发时才体会到。中间件运行在 edge runtime无法直接访问 Node.js 的 MySQL 连接池每次请求都去数据库查询会话状态也不现实。所以我的做法是中间件只做有没有 session cookie的粗拦截细粒度的用户角色校验放在页面或 Server Action 里用 getServerSession 做。4.2 服务端获取会话getServerSession 的正确姿势在页面组件或 Server Action 里使用getServerSession是获取当前登录用户信息的标准做法。先统一封装auth.tsimport { getServerSession } from next-auth; import { authOptions } from /app/api/auth/[...nextauth]/route; export async function getCurrentUser() { const session await getServerSession(authOptions); return session?.user ?? null; }然后在服务端组件里使用import { getCurrentUser } from /lib/session; import { redirect } from next/navigation; export default async function DashboardPage() { const user await getCurrentUser(); if (!user) { redirect(/login); } return ( div h1欢迎回来{user.name}/h1 p你的邮箱{user.email}/p {user.role admin p你有管理员权限/p} /div ); }很多人会忽略的一点服务端页面组件里不要直接调用getSession()。getSession()每次都会发起一个 HTTP 请求到/api/auth/session而getServerSession()是直接读取请求头的 cookie 并进行本地解密性能差距明显。我在项目里统一只用getServerSession。4.3 退出登录Router 的 Server Action 方式退出登录同样用 Server Action 实现NextAuth 提供了signOut函数use server; import { signOut } from /auth; export async function handleSignOut() { await signOut({ redirectTo: /login }); }客户端调用use client; import { handleSignOut } from ./actions; export default function LogoutButton() { return button onClick{() handleSignOut()}退出登录/button; }signOut做了几件事情删除数据库 sessions 表的对应记录、清除浏览器中的 session cookie、重定向到登录页面。整个过程服务端完成你不用手动操作 cookie。这里有一个体验细节退出登录后浏览器里旧的 session cookie 虽然被清掉了但如果用户在退出前打开了多个标签页其他标签页的页面可能还显示着用户信息。这是正常的下次页面刷新或路由跳转时会触发重新校验。4.4 完整的鉴权流程串起来把上面的内容整合整套鉴权链路就是这样的用户访问/dashboard请求先经过 middleware.ts。中间件检查请求 cookie 中是否存在 NextAuth 的 session tokennext-auth.session-token。没有 token说明未登录重定向到/login。有 token放行请求到页面组件。页面组件调用getServerSession从数据库读取会话数据其实这里会查一次 sessions 表确认会话还没过期。如果是管理员页面检查session.user.role是否等于admin不是则重定向。页面渲染将用户信息展示给前端。这套链路里每一步的职责都很清晰中间件做有没有登录的粗判断页面和 Server Action 做是谁、有没有权限的精判断。5. 常见问题与坑位排查实录5.1 登录成功后页面不跳转这是 NextAuth Server Action 最常见的问题。原因通常是signIn的redirectTo参数没有生效或者页面表单没有使用useActionState包装 action。排查思路确认redirectTo用的是完整的路径例如/dashboard而不是dashboard。确认 server action 文件带有use server指令。在开发环境打开浏览器开发者工具的 Network 面板查看登录请求的响应状态码和 Location 头。我遇到过一次很隐蔽的问题登录成功后明明返回了 302但页面没有任何反应。最终发现是登录页的form里没有加action{formAction}而是直接在onSubmit里调用了 server action。这种情况下useActionState的isPending状态能工作但重定向逻辑会异常。改回 form action 就正常了。5.2 Database Session 模式下 session 数据查不到有时登录成功了但页面调用getServerSession返回 null。排查步骤检查sessions表里是否真的新增了一条记录。如果没有说明鉴权流程根本没走到数据库 session 持久化那一步。检查NEXTAUTH_SECRET环境变量是否设置。Database Session 模式下虽然 session 数据存数据库但 cookie 加密仍然依赖 secret。确认 Session 表中session_token字段和 cookie 中的值一致。有次我手动改了 cookie 名导致匹配失败。我在项目中遇到过sessions表里有多条相同 user_id 的记录这是因为每次登录都会新建一条 session而旧 session 没有过期删除。等过期时间到了自然清理就行也不用特意做清理任务updateAge参数会控制更新频率maxAge控制过期时间。5.3 MySQL 连接数爆掉开发环境或者低配服务器上经常出现Too many connections错误。原因基本是连接池配置不合理或者连接没有正常释放。排查思路确认所有数据库查询都用的是同一个 pool 实例不要每个请求新建连接。检查连接池的connectionLimit是否过小默认 10 通常够了但并发高时适当调大。使用pool.query或pool.execute时确保没有在回调里又嵌套执行 SQL 导致连接占用时间过长。另外提一句mysql2 的execute和query是有区别的。execute使用预处理语句prepared statement会缓存执行计划适合重复执行的 SQLquery不走预处理适合一次性查询。对于用户登录这种高频查询推荐用execute。5.4 中间件里无法使用 bcrypt 或 mysql2middleware.ts运行在 Edge Runtime默认不支持 Node.js 原生模块。如果你在中间件里引入了bcryptjs或者mysql2构建时会报错。解决方案很明确中间件里只做 cookie 级别的校验不直接访问数据库。如果需要更精确的权限控制用getServerSession在页面或 API Route 里做。5.5 Cookie 跨域/跨子域问题如果前端和后端分属不同域名例如前端auth.example.com后端 API 在api.example.comNextAuth 的 cookie 需要配置 domain。在authOptions里加cookies: { sessionToken: { name: next-auth.session-token, options: { httpOnly: true, sameSite: lax, path: /, secure: process.env.NODE_ENV production, domain: .example.com, }, }, },这里注意secure: true会导致 HTTPS 环境下 cookie 正常但本地 HTTP 开发环境下 cookie 无法写入。生产环境记得设置开发环境保持 false 或通过环境变量动态判断。5.6 忘记密码/密码重置功能怎么扩展很多项目在登录做完之后下一步就是忘记密码。这里提供一个思路不需要改动 NextAuth 的核心逻辑单独写一个密码重置流程。大致流程是用户输入邮箱生成一个带过期时间的重置 token 存到password_reset_tokens表。将重置链接包含 token通过邮件发送给用户。用户点击链接跳转到重置页面输入新密码。服务端校验 token 有效性后更新users表的password_hash同时删除该用户所有 sessions 记录强制重新登录。强制重新登录那一步很重要。如果不删除旧 session用户在原设备上仍然是登录状态安全上存在隐患。5.7 登录接口被人爆破怎么办鉴权接口天然是攻击面。一些实战中积累的防御手段登录接口加限流。可以用内存限流库生产环境建议用 Redis 做分布式限流。密码错误次数达到阈值后锁定账号一段时间。这个需要在 users 表加failed_attempts和locked_until字段。验证码。简单场景用图形验证码高安全场景可以上行为验证。日志监控。记录登录失败的 IP、邮箱、时间异常时触发告警。5.8 NextAuth 类型扩展使用 TypeScript 时session.user.role初始并没有这个字段需要扩展类型声明。在types/next-auth.d.ts里import { DefaultSession } from next-auth; declare module next-auth { interface Session { user: { id: string; role: string; } DefaultSession[user]; } interface User { id: string; role: string; } }加上这段类型声明后session.user.role和session.user.id就不会报类型错误了。这个文件没有扩展名放在项目根目录或types目录下都会被 tsconfig 自动识别。6. 部署与性能优化实战6.1 环境变量配置部署时环境变量是重头戏。以下是最小集# .env.local 开发环境 NEXTAUTH_URLhttp://localhost:3000 NEXTAUTH_SECRETyour-random-secret-here DB_HOSTlocalhost DB_USERroot DB_PASSWORDyourpassword DB_NAMEauth_demoNEXTAUTH_SECRET务必用强随机字符串可以直接用 openssl 生成openssl rand -base64 32生产环境的 secret 要妥善保管泄露意味着攻击者可以伪造任意用户的 session cookie。前几年不少知名项目就是因为这个泄露翻车的。6.2 Serverless 部署的注意事项如果部署到 Vercel 等 serverless 平台MySQL 连接需要应对冷启动。Vercel 的 Node.js 函数是真正意义上的 serverless每次冷启动都会重新创建连接池MySQL 的连接数很容易被打满。常见的应对方案将数据库连接放到connect()缓存逻辑中利用 global 对象缓存连接池前面已经实现了。购买数据库的最大连接数要留足余量。一般 serverless 平台建议用云数据库并且配置连接复用。考虑在数据库前加一层 PgBouncer 类似的连接池代理MySQL 对应的是 ProxySQL 或 RDS Proxy专门应对大量短连接。不过话说回来如果项目部署在固定服务器比如自己的 VPS 或云主机直接使用常规 Node.js 进程模式反而没这么多烦恼。这就是为什么不少团队最终选择在传统服务器上用 PM2 跑 Next.js 的 standalone 模式。6.3 Session 清理策略数据库 Session 模式会随着时间的推移积累大量已过期记录。虽然 NextAuth 在每次读取时会校验 expires 时间过期 session 本质上不影响功能但表数据膨胀后会影响查询性能。我在项目中写了一个每天执行的清理任务import pool from /lib/db; export async function cleanExpiredSessions() { const [result] await pool.execute( DELETE FROM sessions WHERE expires NOW() ); console.log(清除过期会话: ${result.affectedRows} 条); }用 node-cron 定时调用就行。这个任务对生产环境而言不是必须的但做个定时清理能让系统更健康。7. 写在最后的一些体会这套方案我在两个实际项目中跑过从开发体验和稳定性来说Next.js 15 MySQL NextAuth.js 的组合值得推荐。数据库 Session 模式比 JWT 模式更灵活业务上踢人下线禁用用户权限变更即时生效这类需求都能自然满足。踩过最大的坑还是中间件和数据库 Session 模式的配合问题。文档里withAuth中间件的示例大多基于 JWT照抄过来在 database session 下会碰到 token 为空的情况。理解了中间件只做粗拦截、页面做细校验的分层思路之后整个架构就清晰了。另外鉴权这事别只盯着能登录就完事。密码强度校验、登录限流、越权防护、安全日志每一项都值得花时间做扎实。文章里提到的密码重置、类型扩展、连接池全局复用这些细节都是实打实从生产环境里逼出来的经验照着做能少走不少弯路。最后提醒一句生产环境上线前记得把所有涉及认证的接口用渗透测试工具过一遍别让 SQL 注入和越权这类低级漏洞毁了整个系统。