Communitygithub.com

agents-inc/skills

Auth.js(NextAuth v5)身份验证模式——配置、提供商、会话策略、中间件、数据库适配器、基于角色的访问、Edge 兼容性

skills 是什么?

本技能涵盖 Auth.js(NextAuth v5)在 AI 代理(如 Claude Code、Cursor、Codex)中的完整身份验证模式。它指导用户在根 `auth.ts` 文件中配置 Auth.js,导出 `{ auth, handlers, signIn, signOut }`,并使用统一的 `auth()` 函数访问服务端会话,替换 v4 中已弃用的 `getServerSession`。技能详细介绍了 OAuth 提供商(GitHub、Google 等)、JWT 与数据库会话策略、中间件路由保护、Edge 运行时兼容性(通过拆分 `auth.config.ts` 和 `auth.ts`)以及 Prisma/Drizzle 数据库适配器。还讲解了回调函数(jwt、session、signIn)、基于角色的访问控制、类型扩展以及常见陷阱,如不要将 `signIn()` 包裹在 try/catch 中、不要在中间件中引入数据库 ORM。该指南适用于 Next.js/各种框架项目,并重申必须遵循项目约定(如 CLAUDE.md 中的规范),防止使用已弃用的 API 或造成安全漏洞。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-auth-nextauth

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 兼容性拆分配置

详细资源:

核心模式:


理念

Auth.js (v5) 将身份验证整合到单一、统一的 API 中。auth() 函数用于服务端,替代了 v4 中的 getServerSession、getSession、withAuth 和 getToken。useSession() 仍然是正确的客户端 API。配置位于根文件中,而不是 API 路由中。

核心原则:

  1. 框架无关 - 适用于 Next.js、SvelteKit、Express、Qwik
  2. 统一 API - 单一的 auth() 函数适用于所有服务端上下文
  3. 提供商生态系统 - 80 多个内置 OAuth 提供商,自动检测 AUTH_* 环境变量
  4. 默认 JWT - 在加密的 cookie 中实现无状态会话,无需数据库
  5. Edge 兼容 - 中间件在 Edge 运行时上运行,采用拆分配置(Next.js 16 代理在 Node.js 上运行)
  6. 渐进式复杂 - 从 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>

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

相关技能