# Next.js 身份验证 ## 概述该技能使用 App Router 架构和 Auth.js 5 为 Next.js 15+ 应用程序提供全面的身份验证模式。它涵盖了从初始设置到具有基于角色的访问控制的生产就绪实施的完整身份验证生命周期。主要能力包括： * 使用 Next.js App Router 设置 Auth.js 5 * 使用中间件保护路由 * 服务器组件中的会话管理 * 服务器操作中的身份验证检查 * OAuth 提供商集成（GitHub、Google 等） * 基于角色的访问控制（RBAC） * JWT和数据库会话策略 * 全面的测试模式 ## 何时使用使用 App Router 实现 Next.js 15+ 的身份验证时，请使用此技能： * 从头开始设置 Auth.js 5 (NextAuth.js) * 使用中间件实现受保护的路由 * 处理服务器组件中的身份验证 * 通过身份验证检查保护服务器操作 * 配置 OAuth 提供商（Google、GitHub、Discord 等） * 实施基于角色的访问控制（RBAC） * 使用 JWT 或数据库策略管理会话 * 创建基于凭证的身份验证 * 处理登录/退出流程 * 测试认证流程 ## 说明 ### 1\.安装依赖项为 Next.js 应用程序路由器安装 Auth.js v5（测试版）： npm 安装 next-auth@beta ### 2\.配置环境变量使用所需变量创建 `.env.local`： # Auth.js 必需的 AUTH_SECRET="此处是您的秘密密钥" AUTH_URL =“http://localhost:3000” # OAuth 提供商（根据需要添加） GITHUB_ID="您的 github 客户端 ID" GITHUB_SECRET="您的 github 客户端秘密" GOOGLE_CLIENT_ID="您的 Google 客户端 ID" GOOGLE_CLIENT_SECRET="your-google-client-secret" 使用以下命令生成“AUTH_SECRET”： openssl 兰德-base64 32 ### 3\.创建身份验证配置使用提供程序和回调在项目根目录中创建“auth.ts”：从“next-auth”导入 NextAuth；从“next-auth/providers/github”导入 GitHub；从“next-auth/providers/google”导入 Google；导出常量{ 处理程序：{ GET，POST }，授权，登录，退出， } = NextAuth({ 提供者：[ GitHub({ clientId: process.env.GITHUB_ID!, clientSecret: process.env.GITHUB_SECRET!, }), 谷歌({ clientId：process.env.GOOGLE_CLIENT_ID！， clientSecret：process.env.GOOGLE_CLIENT_SECRET！， }), ], 回调：{ 异步 jwt({ 令牌, 用户 }) { 如果（用户）{ 令牌.id = 用户.id; } 返回令牌； }, 异步会话（{会话，令牌}）{ 如果（令牌）{ session.user.id = token.id 作为字符串； } 返回会话； }, }, 页数：{ 登录：“/登录”，错误：“/错误”， }, }); ### 4\.创建 API 路由处理程序创建 `app/api/auth/[...nextauth]/route.ts`：从“@/auth”导出{ GET, POST }； ### 5\.添加路由保护中间件在项目根目录中创建“middleware.ts”：从“@/auth”导入{auth}；从“next/server”导入{NextResponse}；导出默认身份验证((req) => { const { nextUrl } = 请求； const isLoggedIn = !!req.auth; const isApiAuthRoute = nextUrl.pathname.startsWith("/api/auth"); const isPublicRoute = ["/", "/login", "/register"].includes(nextUrl.pathname); const isProtectedRoute = nextUrl.pathname.startsWith("/dashboard"); if (isApiAuthRoute) 返回 NextResponse.next(); if (!isLoggedIn && isProtectedRoute) { 返回 NextResponse.redirect(new URL("/login", nextUrl)); } if (isLoggedIn && nextUrl.pathname === "/login") { 返回 NextResponse.redirect(new URL("/dashboard", nextUrl)); } 返回 NextResponse.next(); }); 导出常量配置= { 匹配器: ["/((?!_next/static|_next/image|favicon.ico|.*\\.png$).*)"], }; ### 6\.服务器组件中的访问会话使用“auth()”函数访问服务器组件中的会话：从“@/auth”导入{auth}；从“下一步/导航”导入{重定向}；导出默认异步函数 DashboardPage() { const 会话 = 等待 auth(); 如果（！会话）{ 重定向（“/登录”）； } 返回（

欢迎，{session.user.name}

）； } ### 7\.安全服务器操作在突变之前始终验证服务器操作中的身份验证： “使用服务器”；从“@/auth”导入{auth}；导出异步函数 createTodo(formData: FormData) { const 会话 = 等待 auth(); if (!session?.user) { 抛出新错误（“未经授权”）； } // 继续执行受保护的操作 const title = formData.get("title") as string; 等待 db.todo.create({ 数据: { 标题, userId: session.user.id }, }); } ### 8\.处理登录/注销使用服务器操作创建登录页面： // 应用程序/登录/page.tsx 从“@/auth”导入{signIn}；从“下一步/导航”导入{重定向}；导出默认函数LoginPage() { 异步函数handleLogin(formData: FormData) { “使用服务器”； const 结果 = 等待登录（“凭据”，{ 电子邮件：formData.get(“电子邮件”), 密码：formData.get("密码"), 重定向：假， }); if (结果?.错误) { 返回{错误：“凭据无效”}； } 重定向（“/仪表板”）； } 返回（ <表单操作={handleLogin}> <输入名称=“密码”类型=“密码”占位符=“密码”必需/> ）； } 对于客户端注销： “使用客户端”；从“next-auth/react”导入{signOut}；导出函数 SignOutButton() { return ; } ### 9\.实施基于角色的访问检查服务器组件中的角色：从“@/auth”导入{auth}；从“next/navigation”导入{未经授权}；导出默认异步函数 AdminPage() { const 会话 = 等待 auth(); if (session?.user?.role !== "admin") { 未经授权（）； } 返回<管理仪表板/>； } ### 10\.扩展 TypeScript 类型为类型安全会话创建“types/next-auth.d.ts”：从“next-auth”导入{DefaultSession}；声明模块“next-auth”{ 接口会话{ 用户：{ id：字符串；角色：“用户” | “行政”; } & DefaultSession["用户"]; } 界面用户{ 角色？：“用户”| “行政”; } } 声明模块“next-auth/jwt”{ 接口 JWT { id？：字符串；角色？：“用户” | “行政”; } } ## 示例 ### 示例 1：完整受保护的仪表板 **输入：** 用户需要一个只有经过身份验证的用户才能访问的仪表板 **实施：** // 应用程序/仪表板/page.tsx 从“@/auth”导入{auth}；从“下一步/导航”导入{重定向}；从“@/app/lib/data”导入{ getUserTodos }；导出默认异步函数 DashboardPage() { const 会话 = 等待 auth(); if (!session?.user?.id) { 重定向（“/登录”）； } const todos =等待 getUserTodos(session.user.id); 返回（ <主要>

欢迎，{session.user.name}

电子邮件：{session.user.email}

）； } **输出：** 仪表板仅针对经过身份验证的用户及其特定数据呈现。 ### 示例 2：基于角色的管理面板 **输入：** 管理面板只能由具有“admin”角色的用户访问 **实施：** // 应用程序/管理/page.tsx 从“@/auth”导入{auth}；从“next/navigation”导入{未经授权}；导出默认异步函数 AdminPage() { const 会话 = 等待 auth(); if (session?.user?.role !== "admin") { 未经授权（）； } 返回（ <主要>

管理面板

欢迎，管理员{session.user.name}

）； } **输出：** 只有管理员用户才能看到该面板；其他人收到 401 错误。 ### 示例 3：使用表单保护服务器操作 **输入：** 表单提交仅适用于经过身份验证的用户 **实施：** // 应用程序/组件/create-todo-form.tsx “使用服务器”；从“@/auth”导入{auth}；从“next/cache”导入{revalidatePath}；导出异步函数 createTodo(formData: FormData) { const 会话 = 等待 auth(); if (!session?.user?.id) { 抛出新错误（“未经授权”）； } const title = formData.get("title") as string; 等待 db.todo.create({ 数据：{ 标题，用户Id：会话.用户.id， }, }); revalidatePath(“/仪表板”); } // 组件中的使用导出函数 CreateTodoForm() { 返回（ <表单操作={createTodo}> ）； } **输出：** 仅为经过身份验证的用户创建的 Todo；未经授权的请求会引发错误。 ### 示例 4：OAuth 登录按钮 **输入：** 用户应该能够使用 GitHub 登录 **实施：** // 组件/auth/sign-in-button.tsx “使用客户端”；从“next-auth/react”导入{signIn、signOut、useSession}；导出函数 AuthButton() { const { 数据：会话，状态 } = useSession(); 如果（状态===“正在加载”）{ 返回<按钮已禁用>正在加载...; } 如果（会话）{ 返回（ <按钮 onClick={() => SignOut()}> 退出 {session.user?.name} ）； } 返回（ <按钮 onClick={() => 登录("github")}> 使用 GitHub 登录）； } **输出：** 对于未经身份验证的用户，按钮显示“使用 GitHub 登录”，对于经过身份验证的用户，按钮显示“注销 {name}”。 ### 示例 5：凭证提供者登录 **输入：** 实施电子邮件/密码登录 **实施：** // 验证.ts 从“next-auth/providers/credentials”导入凭证；从“bcryptjs”导入bcrypt；导出 const { 处理程序、 auth、登录、退出 } = NextAuth({ 提供者：[ 凭证（{ 名称：“凭证”，凭证：{ 电子邮件：{ 标签：“电子邮件”，类型：“电子邮件”}，密码：{ 标签：“密码”，类型：“密码”}， }, 异步授权（凭据）{ if (!credentials?.email || !credentials?.password) { 返回空值； } const 用户 = 等待 db.user.findUnique({ 其中：{电子邮件：凭据.电子邮件}， }); if (!user || !user.password) { 返回空值； } const isValid = 等待 bcrypt.compare( 凭证.密码，用户名.密码）；返回有效？ { id: user.id, email: user.email, name: user.name } ：空； }, }), ], }); **输出：** 用户可以使用电子邮件/密码针对您的数据库进行身份验证。 ## 最佳实践 1. **默认使用服务器组件** \- 无需客户端 JavaScript 直接访问会话 2. **最小化客户端组件** \- 仅使用 `useSession()` 进行反应式会话更新 3. **缓存会话检查** \- 使用 React 的 `cache()` 在同一渲染中重复查找 4. **用于乐观检查的中间件** \- 快速重定向，但始终在服务器操作中重新验证 5. **将服务器操作视为 API 端点** \- 始终在突变之前进行身份验证 6. **切勿对机密进行硬编码** \- 对所有凭据使用环境变量 7. **实施正确的错误处理** \- 返回适当的 HTTP 状态代码 8. **使用 TypeScript 类型扩展** \- 为自定义字段扩展 NextAuth 类型 9. **单独的身份验证逻辑** \- 创建 DAL（数据访问层）以进行一致性检查 10. **测试身份验证流程** \- 在单元测试中模拟 `auth()` 函数 ## 限制和警告 ### 关键限制 * **中间件在 Edge 运行时上运行** \- 无法像数据库驱动程序一样使用 Node.js API * **服务器组件无法设置 cookie** \- 使用服务器操作进行 cookie 操作 * **会话回调计时** \- 仅在会话创建/访问时调用，而不是每个请求 ### 常见错误 // ❌ 错误：在服务器组件中设置 cookie 导出默认异步函数 Page() { cookies().set("键", "值"); // 不会工作 } // ✅ 正确：使用服务器操作异步函数 setCookieAction() { “使用服务器”； cookies().set("键", "值"); } // ❌ 错误：中间件中的数据库查询导出默认身份验证（异步（请求）=> { const user = wait db.user.findUnique(); // 在 Edge 中不起作用 }); // ✅ 正确：仅使用边缘兼容的 API 导出默认身份验证（异步（请求）=> { const 会话 = req.auth; // 这有效 }); ### 安全考虑 * 始终在服务器操作中验证身份验证 - 仅中间件是不够的 * 对于未经身份验证的访问使用“unauthorized()”，对于其他情况使用“redirect()” * 将敏感令牌存储在 `httpOnly` cookie 中 * 在处理之前验证所有用户输入 * 在生产中使用HTTPS * 设置适当的 cookie `sameSite` 属性 ## 参考文献 * [references/authjs-setup.md]() \- 使用 Prisma/Drizzle 适配器完成 Auth.js 5 设置指南 * [references/oauth-providers.md]() \- 特定于提供商的配置（GitHub、Google、Discord、Auth0 等） * [references/database-adapter.md]() \- 使用 Prisma、Drizzle 和自定义适配器进行数据库会话管理 * [references/testing-patterns.md]() \- 使用 Vitest 和 Playwright 测试身份验证流程

Nextjs 身份验证

包含技能