用途
本技能用于在 Next.js 项目中搭建 Auth.js v5 认证体系，覆盖从安装、环境变量配置到登录、会话管理与路由保护的完整流程。官方说明 Auth.js v5 目前处于 beta 阶段，需通过 next-auth@beta 安装最新 v5 版本。
主要能力
- 支持 Google OAuth 与 Credentials（用户名/密码）两种登录方式。
- 提供统一的 auth() 导出，可在服务端组件、Server Actions、中间件等场景中调用。
- 支持 JWT 与 Database 两种会话策略。
- 提供 signIn、signOut、handlers 等核心 API。
- 支持通过回调（signIn、jwt、session、authorized、redirect）扩展认证逻辑。
- 可选 Prisma 数据库适配器，用于持久化用户、账户与会话。
- 官方称 v5 相较 v4 的改进包括：更简化的配置、更好的 TypeScript 支持、增强的 CSRF 保护与会话处理、Edge Runtime 兼容性。
使用方式
安装
pnpm add next-auth@beta
使用 Credentials 时还需安装：
pnpm add bcryptjs zod
pnpm add -D @types/bcryptjs
使用数据库适配器时：
pnpm add @auth/prisma-adapter
环境变量
AUTH_SECRET=your_secret_key_here
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret
AUTH_URL=https://yourdomain.com
生成 AUTH_SECRET 的方式：
openssl rand -base64 32
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
pnpm dlx auth secret
官方提示：切勿将 AUTH_SECRET 提交到版本控制，开发环境使用 .env.local。
基础配置
在项目根目录（与 package.json 同级）创建 auth.ts，导入 NextAuth 及所需 provider，导出 handlers、signIn、signOut、auth。示例中配置了 Google 与 Credentials 两个 provider、自定义登录页 pages.signIn 以及 authorized 回调。
创建 API 路由处理器 app/api/auth/[...nextauth]/route.ts：
import { handlers } from "@/auth"
export const { GET, POST } = handlers
可选但推荐添加 middleware.ts，可直接导出 auth 作为 middleware，或使用 auth((req) => {...}) 自定义逻辑，并通过 config.matcher 指定匹配路径。
Google OAuth
需在 Google Cloud Console 创建项目、启用 Google+ API、创建 OAuth 2.0 凭据（应用类型为 Web application），并配置授权重定向 URI：
- 开发：http://localhost:3000/api/auth/callback/google
- 生产：https://yourdomain.com/api/auth/callback/google
配置中可设置 authorization.params（如 prompt、access_type、response_type、scope）以及 allowDangerousEmailAccountLinking。
Credentials Provider
使用 zod 校验凭据（email、password），通过 bcrypt.compare 校验密码，从数据库（示例使用 Prisma）查询用户，返回包含 id 的用户对象。官方说明 Credentials provider 必须使用 session.strategy 为 "jwt"。文档还提供了用户注册接口示例（app/api/auth/register/route.ts），包含重复用户检查、bcrypt.hash 哈希密码与创建用户。
在组件中使用
- 服务端组件：调用 await auth() 获取 session。
- Server Actions：调用 await auth() 校验身份后执行数据库更新并 revalidatePath。
- 客户端组件：使用 SessionProvider 包裹应用，通过 useSession、signIn、signOut 使用。
登录/登出
可通过 signIn(provider)、signIn("credentials", formData)、signIn("google", { redirectTo: "/dashboard" }) 等方式调用，也可在表单的 action 中以 Server Action 形式调用 signIn 与 signOut。
会话管理
支持 jwt（默认）与 database 两种策略，可配置 maxAge、updateAge。可通过声明合并扩展 Session 类型，并在 jwt 与 session 回调中写入 id、role 等字段。
回调
文档列出 signIn、jwt、session、authorized、redirect 等回调的用途与示例，例如在 signIn 中校验 Google 邮箱是否已验证，在 authorized 中判断是否登录并保护 /dashboard 路径。
数据库适配器
使用 PrismaAdapter(prisma) 并设置 session.strategy 为 "database"，文档给出了 User、Account、Session 三个 Prisma model 的 schema 定义。
适用场景
适用于使用 Next.js App Router 的项目，需要实现 Google 登录、用户名密码登录、会话管理、中间件路由保护以及数据库持久化用户与会话等认证需求。
限制
官方说明 Auth.js v5 目前处于 beta 阶段。文档中的 Credentials 示例为占位实现，需自行替换为实际数据库查询逻辑。其他未在资料中说明的功能、收费、价格、平台或效果暂未提供。