# 🔑 技能：auth-expert (v2.0.0) ## 🌟 2026 年概述和愿景此技能可以深入了解 **Auth.js v5**（NextAuth.js 的后继者）。它专门针对 **Next.js 16.1.1** 应用程序路由器、**React 19.2** 服务器操作和 **Edge Runtime** 约束进行了优化。 2026 年，身份验证不再只是登录表单；而是身份验证。它涉及一个统一的会话架构，可以跨服务器组件、客户端组件、中间件和服务器操作工作，而无需牺牲性能。 ** ** ## 📚 目录 1. 核心架构：双配置模式 2. 快速启动：5 分钟设置 3. 通用身份验证：`auth()`协议 4. 路由保护与中间件 5. React 19 服务器操作和身份验证 6.“不要”清单（常见陷阱） 7. 安全强化检查表 8. 高级模式：类型和可扩展性 9. 深入探讨（参考文献） ** ** ## 🏗️ 核心架构：双配置模式为了避免 Edge 运行时（中间件）中出现“找不到模块”错误，Auth.js v5 需要拆分配置。 ### 1\.边缘兼容逻辑（`auth.config.ts`）该文件仅包含可以在 Edge 上运行的逻辑。 **切勿在此处导入数据库适配器或繁重的 Node.js 库。** 从“next-auth”导入类型 { NextAuthConfig }；从“next-auth/providers/github”导入 GitHub； // 这是中间件和边缘功能的基本配置导出常量 authConfig = { 提供者：[ GitHub({ clientId: process.env.AUTH_GITHUB_ID, clientSecret：process.env.AUTH_GITHUB_SECRET， }), ], 回调：{ 授权({ auth, 请求: { nextUrl } }) { const isLoggedIn = !!auth?.user; const isOnDashboard = nextUrl.pathname.startsWith("/dashboard"); 如果（isOnDashboard）{ if (isLoggedIn) 返回 true；返回假； // 重定向未经身份验证的用户登录 } 返回真； }, }, } 满足 NextAuthConfig； ### 2\.完整逻辑（`auth.ts`）此文件导入 `authConfig` 并添加数据库适配器（Node.js 运行时）。从“next-auth”导入 NextAuth；从“@auth/prisma-adapter”导入 { PrismaAdapter }；从“@/lib/db”导入{prisma}； // 您的 Prisma 客户端从“./auth.config”导入{authConfig}；导出常量{ 处理程序，授权，登录，退出， update // 用于手动更新会话 } = NextAuth({ 适配器：PrismaAdapter(prisma)， session: { Strategy: "jwt" }, // JWT 对于 Edge 兼容性是必需的 ...authConfig， }); ** ** ## ⚡ 快速入门：5 分钟设置 ### 第 1 步：安装依赖项添加 next-auth@beta @auth/prisma-adapter ### 步骤2：配置环境变量 # 生成方式：npx auth Secret AUTH_SECRET=your_ultra_secure_secret_here # 提供商凭证 AUTH_GITHUB_ID=... AUTH_GITHUB_SECRET=... ### 步骤 3：创建路由处理程序 `app/api/auth/[...nextauth]/route.ts` 从“@/auth”导入{处理程序}；导出 const { GET, POST } = 处理程序； ** ** ## 🌍 通用身份验证：`auth()` 协议 v5 最强大的功能之一是通用的“auth()”函数。它在任何地方都有效。 ### 1\.在服务器组件 (RSC) 中从“@/auth”导入{auth}；导出默认异步函数 ProfilePage() { const 会话 = 等待 auth(); 如果（！会话）{ return

未登录。

; } 返回（

欢迎，{session.user?.name}

角色：{session.user?.role}

）； } ### 2\.在服务器操作中 “使用服务器” 从“@/auth”导入{auth}；导出异步函数 createPost(content: string) { const 会话 = 等待 auth(); if (!session) throw new Error("未经授权"); // 安全访问用户数据 constauthorId = session.user.id; // ... 数据库逻辑 } ### 3\.在客户端组件中使用“next-auth/react”中的“useSession”挂钩。 **注意**：您必须将您的应用程序包装在“”中。 “使用客户端” 从“next-auth/react”导入{useSession}；导出函数 UserButton() { const { 数据：会话，状态 } = useSession(); if (status === "loading") return

...

; if (!session) return ; return

; } ** ** ## 🛡️ 路由保护和中间件 `middleware.ts` 文件是第一道防线。从“next-auth”导入 NextAuth；从“./auth.config”导入{authConfig}；导出默认 NextAuth(authConfig).auth; 导出常量配置= { // 如果需要，匹配器允许排除静态文件和 api 路由匹配器: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], }; ** ** ## 🧪 React 19 服务器操作和身份验证 React 19 引入了改进的表单和转换处理。将它们用于您的登录流程。 ### 登录操作示例 “使用服务器” 从“@/auth”导入{signIn}；从“next-auth”导入{AuthError}；导出异步函数验证（上一个状态：字符串 |未定义，表单数据：表单数据，）{ 尝试{ 等待登录（“凭据”，formData）； } 捕获（错误）{ if (AuthError 错误实例) { 开关（错误类型）{ 案例“凭据登录”：返回“无效凭据。”；默认： return“出了点问题。”； } } 抛出错误； } } ** ** ## 🚫 “不要”清单（常见陷阱）陷阱|为什么不好|解决方案 ---|---|--- **使用`getServerSession`** | v4 旧版本，v5 速度较慢。 |使用“auth()”。 **`NEXTAUTH_URL`** |在 v5 中已弃用。 |使用“AUTH_URL”或让它自动检测。 **中间件中的 Prisma** |中间件运行在Edge上； Prisma 需要 Node。 |使用拆分配置模式。 **仅客户端检查** |通过禁用 JS 可以轻松绕过。 |始终验证服务器上的会话。 **在客户端中存储秘密** |安全漏洞。 |将所有秘密保存在“.env.local”中。 **忽略 CSRF** |容易受到跨站点攻击。 |使用内置处理程序和操作。 ** ** ## 🏁 安全强化清单 * **轮换机密** ：确保定期轮换“AUTH_SECRET”。 * **安全 Cookies** ：在生产中，cookie 自动是安全的，但要验证 `trustHost`。 * **角色验证** ：不要只检查`!!session`，检查`session.user.role === 'admin'`。 * **速率限制** ：对 `app/api/auth` 端点应用速率限制。 * **仅限 HTTPS** ：确保您的站点通过 HTTPS 提供服务以保护会话 cookie。 ** ** ## 🔧 高级模式：类型和可扩展性扩展会话对象是一个常见的需求。 ### `next-auth.d.ts` 从“next-auth”导入{ type DefaultSession }；导出类型 ExtendedUser = DefaultSession["user"] & { 角色：“管理员”| “用户”; id：字符串； }; 声明模块“next-auth”{ 接口会话{ 用户：扩展用户； } } ### 角色的回调逻辑回调：{ 异步会话（{ 令牌，会话 }）{ if (token.sub && session.user) { session.user.id = token.sub; } if (token.role && session.user) { session.user.role = token.role 作为“ADMIN” | “用户”; } 返回会话； }, 异步 jwt({ 令牌 }) { if (!token.sub) 返回令牌；常量现有用户 = 等待 getUserById(token.sub); if (!existingUser) 返回令牌； token.role = 现有用户.role; 返回令牌； } } ** ** ## 📖 深入探讨（参考资料）对于更复杂的场景，请参阅以下专业指南： * [边缘兼容性和运行时]() * [高级提供商和自定义逻辑]() * [安全最佳实践]() ** ** ## 🛠️ 故障排除 ###“JWT 已过期”或“签名无效” 检查您的“AUTH_SECRET”是否在所有环境中都匹配。如果您更改它，则所有当前会话都将失效。 ###“重定向递归” 当您的“middleware.ts”逻辑重定向到“/login”但未从中间件匹配器或“authorized”检查中排除“/login”时，通常会发生这种情况。 ** ** ## 🗄️ 高级数据库集成：自定义模式使用 Prisma 或 Drizzle 时，您可能需要自定义表名称或添加额外字段。 ### Prisma 架构示例 // schema.prisma 模型用户{ id 字符串 @id @default(cuid()) 名称字符串？电子邮件字符串？ @独特电子邮件验证日期时间？图像字符串？角色 UserRole @default(USER) 账户账户[] 会话会话[] 创建于日期时间@default(now()) 更新日期时间@updatedAt } 枚举用户角色{ 管理员用户 } 模型帐户 { id 字符串 @id @default(cuid()) 用户 ID 字符串类型字符串提供者字符串提供者帐户 ID 字符串刷新令牌字符串？ @db.Text access_token 字符串？ @db.Text expires_at Int? token_type 字符串？范围字符串？ id_token 字符串？ @db.Text 会话状态字符串？ user 用户@relation（字段：[userId]，引用：[id]，onDelete：级联） @@unique([提供者, 提供者AccountId]) } ### 毛毛雨模式示例导入{ 时间戳， pg表，文字，主键，整数， } 来自“drizzle-orm/pg-core” 从 '@auth/core/adapters' 导入类型 { AdapterAccount } 导出常量用户 = pgTable("用户", { id: text("id").notNull().primaryKey(), 名称：文本（“名称”），电子邮件：文本（“电子邮件”）.notNull（）， emailVerified: 时间戳("emailVerified", { mode: "日期" }), 图像：文本（“图像”）， }) 导出常量帐户 = pgTable( “账户”， { 用户ID：文本（“用户ID”） .notNull() .references(() => users.id, { onDelete: "cascade" }), 类型：text("type").$type().notNull(), 提供者：文本（“提供者”）.notNull（）， providerAccountId: text("providerAccountId").notNull(), 刷新令牌：文本（“刷新令牌”），访问令牌：文本（“访问令牌”），过期时间：整数（“过期时间”），令牌类型：文本（“令牌类型”），范围：文本（“范围”）， id_token：文本（“id_token”），会话状态：文本（“会话状态”）， }, （帐户）=>（{ compoundKey: PrimaryKey({ columns: [account.provider, account.providerAccountId] }), }) ） ** ** ## 🌐 国际化 (i18n) 和身份验证处理多种语言的重定向和错误消息。 ### i18n 感知重定向如果您使用“next-intl”或类似的库，您的身份验证逻辑应该尊重当前的区域设置。 // auth.config.ts 回调：{ 授权({ auth, 请求: { nextUrl } }) { const locale = nextUrl.pathname.split('/')[1] || '恩'; const isLoggedIn = !!auth?.user; if (nextUrl.pathname.startsWith(`/${locale}/dashboard`) && !isLoggedIn) { return Response.redirect(new URL(`/${locale}/login`, nextUrl)); } 返回真； } } ** ** ## 🛡️ 2026 年多重身份验证 (MFA) 虽然 Auth.js 没有“一键”MFA，但您可以使用“回调”和自定义会话状态来实现它。 ### 实施策略 1. **第一个因素**：标准登录（OAuth/凭据）。 2. **MFA 检查** ：登录后，检查用户是否启用了 MFA。 3. **临时会话**：如果需要 MFA，请将 JWT 标记为 `mfa_pending: true`。 4. **验证** ：重定向到 `/verify-mfa` 页面。 5. **最终**：验证后，将 JWT 更新为 `mfa_verified: true`。 // MFA 的 JWT 回调示例异步 jwt({ 令牌, 用户 }) { 如果（用户）{ token.mfa_required = user.hasMfa; token.mfa_verified = false; } 返回令牌； } // 在中间件中 if (token?.mfa_required && !token?.mfa_verified && 路径名 !== "/verify-mfa") { return Response.redirect(new URL("/verify-mfa", nextUrl)); } ** ** ## 🧪 测试身份验证测试身份验证流程对于防止回归至关重要。 ### 1\.使用 Vitest 进行集成测试模拟“auth”函数来测试受保护的组件。从 'vitest' 导入 { vi, test, Expect }; 从'@/auth'导入{auth}； vi.mock('@/auth', () => ({ 授权： vi.fn(), })); test('向登录用户显示秘密内容', async () => { (auth as any).mockResolvedValue({ user: { name: '测试用户' } }); // 渲染组件并断言 }); ### 2\.与剧作家进行端到端测试使用专用测试用户和“storageState”功能在测试中保持登录状态。从“@playwright/test”导入{测试，期望}； test('登录后可以访问仪表板', async ({ page }) => { 等待 page.goto('/login'); 等待 page.fill('input[name="email"]', 'test@example.com'); 等待页面.fill（'输入[名称=“密码”]'，'密码'）; 等待 page.click('button[type="submit"]'); 等待期望（页面）.toHaveURL（'/仪表板'）; }); ** ** ## 🔗 外部资源 * [Auth.js v5 官方文档]() * [Auth.js GitHub 存储库]() * [Prisma 适配器文档]() ** ** ## 📜 完整的实施示例（“黄金标准”） ### `auth.config.ts` 从“next-auth”导入类型 { NextAuthConfig }；从“next-auth/providers/github”导入 GitHub；从“next-auth/providers/credentials”导入凭证；导出常量 authConfig = { 提供者：[ GitHub，凭证（{ 异步授权（凭据）{ // 验证逻辑在这里返回空值； } }) ], 回调：{ 授权({ auth, 请求: { nextUrl } }) { // 这里的逻辑返回真； } } } 满足 NextAuthConfig； ### `auth.ts` 从“next-auth”导入 NextAuth；从“@auth/drizzle-adapter”导入{ DrizzleAdapter }；从“@/db”导入{db}；从“./auth.config”导入{authConfig}；导出 const { auth, 处理程序, 登录, 退出 } = NextAuth({ 适配器：DrizzleAdapter(db), 会话：{策略：“jwt”}， ...authConfig， }); ### `中间件.ts` 从“next-auth”导入 NextAuth；从“./auth.config”导入{authConfig}；导出默认 NextAuth(authConfig).auth; 导出常量配置= { 匹配器: ["/((?!api|_next/static|_next/image|favicon.ico).*)"], }; ** ** _更新时间：2026 年 1 月 22 日 - 15:18_

认证专家

包含技能