Auth.js (NextAuth v5) 模式
快速指南: 在根目录
auth.ts文件中配置 Auth.js,导出NextAuth()返回的{ auth, handlers, signIn, signOut }。在所有地方(服务器组件、路由处理程序、中间件)使用统一的auth()函数。默认会话策略是 JWT(基于 cookie);添加数据库适配器以实现持久会话。通过中间件或按页面的auth()检查来保护路由。
<critical_requirements>
关键:使用此技能前务必了解
所有代码必须遵循 CLAUDE.md 中的项目约定(kebab-case、命名导出、导入顺序、
import type、命名常量)
(你必须在根目录 auth.ts 文件中配置 Auth.js,并导出 NextAuth() 返回的 { auth, handlers, signIn, signOut })
(你必须使用统一的 auth() 函数进行服务端会话访问——不要使用已弃用的 getServerSession()、getSession() 或 getToken())
(你必须使用 AUTH_SECRET 环境变量——NEXTAUTH_SECRET 在 v5 中已弃用)
(你必须为提供商凭证使用 AUTH_ 前缀的环境变量(例如 AUTH_GITHUB_ID、AUTH_GITHUB_SECRET)——它们会被自动检测)
(当结合中间件使用数据库会话时,你必须将 Auth 配置拆分为 auth.config.ts(Edge 兼容)和 auth.ts(带适配器))
(你必须在服务器操作和 API 路由中检查会话——仅靠中间件不足以进行授权)
</critical_requirements>
自动检测: Auth.js、NextAuth、next-auth、authjs、auth.ts、auth.config.ts、NextAuth()、signIn、signOut、auth()、handlers、SessionProvider、useSession、AUTH_SECRET、OAuth 提供商、凭证提供商、数据库适配器、@auth/prisma-adapter、@auth/drizzle-adapter、authorized 回调、jwt 回调、session 回调、代理认证、中间件认证
何时使用:
- 为 Next.js、SvelteKit、Express 或 Qwik 应用添加身份验证
- 实现 OAuth 登录(GitHub、Google、Discord 等),拥有 80 多个内置提供商
- 构建电子邮件/魔法链接身份验证流程
- 需要 JWT 或数据库支持的会话管理
- 需要 Edge 兼容的中间件身份验证的项目
何时避免使用:
- 从头构建自定义的身份验证系统(Auth.js 是定制的)
- 需要开箱即用的精细组织/团队管理
- 没有 Web 前端的纯移动应用
- 需要具有插件架构的自托管身份验证
涵盖的关键模式:
- Auth 配置(
auth.ts、auth.config.ts) - OAuth 提供商(GitHub、Google、Credentials、Email)
- 会话策略(JWT 与数据库)
- 会话访问(服务器组件、路由处理程序、客户端组件)
- 中间件/代理路由保护
- 数据库适配器(Prisma、Drizzle)
- 回调(jwt、session、signIn、redirect)
- 基于角色的访问控制
- Edge 兼容性拆分配置
详细资源:
- 关于决策框架和反模式,请参阅 reference.md
核心模式:
- examples/core.md - Auth 配置、提供商、回调
- examples/session.md - 会话策略、会话访问模式
- examples/middleware.md - 路由保护、中间件、Edge 兼容性
- examples/database.md - 数据库适配器、Prisma、Drizzle
- examples/patterns.md - 基于角色的访问、魔法链接、账户关联
理念
Auth.js (v5) 将身份验证整合到单一、统一的 API 中。auth() 函数用于服务端,替代了 v4 中的 getServerSession、getSession、withAuth 和 getToken。useSession() 仍然是正确的客户端 API。配置位于根文件中,而不是 API 路由中。
核心原则:
- 框架无关 - 适用于 Next.js、SvelteKit、Express、Qwik
- 统一 API - 单一的
auth()函数适用于所有服务端上下文 - 提供商生态系统 - 80 多个内置 OAuth 提供商,自动检测
AUTH_*环境变量 - 默认 JWT - 在加密的 cookie 中实现无状态会话,无需数据库
- Edge 兼容 - 中间件在 Edge 运行时上运行,采用拆分配置(Next.js 16 代理在 Node.js 上运行)
- 渐进式复杂 - 从 OAuth 开始,添加数据库适配器,然后自定义回调
核心模式
模式 1:Auth 配置
中心配置文件从 NextAuth() 导出你所需的一切。
基本 OAuth 设置
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
export const { auth, handlers, signIn, signOut } = NextAuth({
providers: [
GitHub, // 自动检测 AUTH_GITHUB_ID 和 AUTH_GITHUB_SECRET
Google, // 自动检测 AUTH_GOOGLE_ID、AUTH_GOOGLE_SECRET
],
});
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;
优点: 单个配置文件导出所有身份验证实用程序,提供商自动检测 AUTH_* 环境变量,API 路由非常简洁
环境变量
# .env.local
AUTH_SECRET="generate-with-npx-auth-secret" # 必需
AUTH_GITHUB_ID="your-github-client-id" # 被 GitHub 提供商自动检测
AUTH_GITHUB_SECRET="your-github-secret" # 被 GitHub 提供商自动检测
AUTH_GOOGLE_ID="your-google-id" # 被 Google 提供商自动检测
AUTH_GOOGLE_SECRET="your-google-secret"
优点: AUTH_ 前缀在 v5 中是标准化的,AUTH_SECRET 替代了已弃用的 NEXTAUTH_SECRET,提供商自动检测凭证
模式 2:提供商
Auth.js 支持 OAuth、电子邮件/魔法链接和凭证身份验证。80 多个内置 OAuth 提供商自动检测 AUTH_* 环境变量。
// OAuth:自定义配置文件映射
GitHub({
profile(profile) {
return {
id: String(profile.id),
name: profile.name ?? profile.login,
role: "user",
};
},
});
// Credentials:验证输入,失败时返回 null
Credentials({
async authorize(credentials) {
const parsed = LoginSchema.safeParse(credentials);
if (!parsed.success) return null;
const user = await getUserByEmail(parsed.data.email);
if (
!user ||
!(await verifyPassword(parsed.data.password, user.hashedPassword))
)
return null;
return { id: user.id, name: user.name, email: user.email };
},
});
关键规则: 在数据库查询前验证输入,始终对密码进行哈希处理,失败时返回 null(绝不抛出异常——会泄露信息)。有关完整实现,请参阅 examples/core.md。
模式 3:回调
四个回调自定义身份验证行为。数据流:jwt 回调(丰富令牌)-> session 回调(暴露给客户端)。
callbacks: {
jwt({ token, user }) {
if (user) { token.id = user.id; token.role = user.role ?? "user"; }
return token;
},
session({ session, token }) {
session.user.id = token.id as string;
session.user.role = token.role as string;
return session;
},
}
关键规则: JWT 回调在每次 auth() 调用时都会运行(保持轻量),user 参数仅在登录时存在,绝不将 OAuth 令牌暴露给客户端。有关完整的回调实现(包括 signIn 和 redirect),请参阅 examples/core.md。
模式 4:会话访问
统一的 auth() 函数用于服务端,替代了 v4 中的 getServerSession、getSession 和 getToken。useSession() 仍用于客户端组件。
| 上下文 | 如何访问会话 |
|---|---|
| 服务器组件 | const session = await auth() |
| 路由处理程序 | export const GET = auth(function GET(req) { req.auth }) |
| 服务器操作 | const session = await auth() |
| 中间件/代理 | export { auth as middleware} 或 authorized 回调 |
| 客户端组件 | useSession()(需要在布局中提供 SessionProvider) |
关键规则: 服务端导入来自 @/auth,客户端导入来自 next-auth/react。绝不在客户端组件中调用 auth()。有关完整实现,请参阅 examples/session.md。
模式 5:登录/注销操作
两种方法:服务器操作(推荐,渐进增强)或客户端。
// 服务端(推荐):从 @/auth 导入,在表单中使用服务器操作
import { signIn, signOut } from "@/auth";
// 在表单操作中:await signIn("github", { redirectTo: "/dashboard" })
// 在表单操作中:await signOut({ redirectTo: "/" })
// 客户端:从 next-auth/react 导入,使用 onClick 处理程序
import { signIn, signOut } from "next-auth/react";
// onClick:signIn("github", { callbackUrl: "/dashboard" })
关键规则: 服务端使用 redirectTo,客户端使用 callbackUrl。signIn() 内部会抛出 NEXT_REDIRECT 异常——不要将其包裹在 try/catch 中期望返回值。有关完整实现,请参阅 examples/core.md。
模式 6:TypeScript 扩展
通过在 types/next-auth.d.ts 中进行声明合并来扩展会话和 JWT 类型。使用 & DefaultSession["user"] 在 Session、User 和 JWT 接口上声明自定义字段(例如 id、role)以保留默认值。请参阅 examples/core.md 获取完整的类型声明示例。
集成指南
Auth.js 是身份验证层。 它处理身份验证、会话管理和路由保护。它不处理授权逻辑(角色检查、权限系统)——那是应用层代码。
框架支持: Auth.js 通过特定框架的包(next-auth、@auth/sveltekit、@auth/express)与多种 Web 框架一起工作。
数据库适配器: 对于数据库会话,Auth.js 提供适配器包(@auth/prisma-adapter、@auth/drizzle-adapter 等),与你的 ORM 集成。请参阅 examples/database.md。
会话策略取决于你的需求:
- JWT(默认) - 无需数据库,适用于 Edge,无状态
- 数据库 - 需要适配器,服务端会话存储,支持即时撤销
Auth.js 不处理: 细粒度授权/RBAC、速率限制或超出身份验证范围的数据库查询——这些是应用层关注点。
<red_flags>
危险标志
- 使用
getServerSession(authOptions)—— 在 v5 中已弃用;请使用auth.ts中的auth() - 使用
NEXTAUTH_SECRET或NEXTAUTH_URL—— 已弃用;请使用AUTH_SECRET(URL 会自动检测) - 凭证提供商没有速率限制 —— 容易受到暴力攻击
- 通过 session 回调将 OAuth 令牌暴露给客户端 —— 将
accessToken/refreshToken仅保留在服务端 - 仅靠中间件/代理进行授权 —— 它在渲染前运行,但不能替代服务器操作/API 路由中的逐路由检查
- 在中间件中导入数据库适配器 —— 数据库 ORM 无法在 Edge 运行时上运行(Next.js 14/15);将配置拆分为
auth.config.ts+auth.ts - 将
signIn()包裹在 try/catch 中 —— 它内部会抛出 NEXT_REDIRECT 异常(这是有意设计的) - JWT 回调每次调用都查询数据库 —— 它在每次
auth()调用时运行;保持轻量
请参阅 reference.md 了解完整的反模式列表、陷阱和迁移表。
</red_flags>
<critical_reminders>
关键提醒
所有代码必须遵循 CLAUDE.md 中的项目约定
(你必须在根目录 auth.ts 文件中配置 Auth.js,并导出 NextAuth() 返回的 { auth, handlers, signIn, signOut })
(你必须使用统一的 auth() 函数进行服务端会话访问——不要使用已弃用的 getServerSession()、getSession() 或 getToken())
(你必须使用 AUTH_SECRET 环境变量——NEXTAUTH_SECRET 在 v5 中已弃用)
(你必须为提供商凭证使用 AUTH_ 前缀的环境变量(例如 AUTH_GITHUB_ID、AUTH_GITHUB_SECRET)——它们会被自动检测)
(当结合中间件使用数据库会话时,你必须将 Auth 配置拆分为 auth.config.ts(Edge 兼容)和 auth.ts(带适配器))
(你必须在服务器操作和 API 路由中检查会话——仅靠中间件不足以进行授权)
未能遵循这些规则将导致身份验证失败、暴露已弃用的模式或造成安全漏洞。
</critical_reminders>