在 Next.js App Router 中集成…

当需要在 Next.js 项目中用 Auth.js v5 实现 Google OAuth、邮箱密码登录、会话管理和路由保护时使用。

适用场景

解决思路

1. 安装 Auth.js v5 beta：运行 `pnpm add next-auth@beta`。
2. 利用 v5 变化：使用简化配置和 universal `auth()` 导出；依赖增强 CSRF/session 处理；middleware 兼容 Edge Runtime；使用改进的 TypeScript 定义。
3. 在 `.env.local` 配置必需环境变量：`AUTH_SECRET=your_secret_key_here`；如用 Google provider，设置 `AUTH_GOOGLE_ID=your_google_client_id`、`AUTH_GOOGLE_SECRET=your_google_client_secret`；生产设置 `AUTH_URL=https://yourdomain.com`；开发可设置 `AUTH_URL=http://localhost:3000`。
4. 生成 `AUTH_SECRET`：运行 `openssl rand -base64 32`，或 `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`，或 `pnpm dlx auth secret`；不要把 `AUTH_SECRET` 提交到版本控制。
5. 在项目根目录（`package.json` 旁）创建 `auth.ts`，从 `next-auth`、`next-auth/providers/google`、`next-auth/providers/credentials` 导入，执行 `export const { handlers, signIn, signOut, auth } = NextAuth({ ... })`。
6. 在 `auth.ts` 的 `providers` 中配置 `Google({ clientId: process.env.AUTH_GOOGLE_ID, clientSecret: process.env.AUTH_GOOGLE_SECRET })`；可添加 `authorization: { params: { prompt: "consent", access_type: "offline", response_type: "code", scope: "openid email profile", prompt: "select_account" } }`，并设置 `allowDangerousEmailAccountLinking: false`。
7. 配置 Credentials provider：定义 `credentials` 字段 `email`、`password`；在 `authorize` 中校验凭证，数据库查用户，`bcrypt.compare` 验证密码，返回必须包含 `id`、`email`、`name`、`image` 的用户对象，失败返回 `null`；生产用 `zod` schema `z.object({ email: z.string().email(), password: z.string().min(8) })`。
8. 在 `auth.ts` 中配置 `pages: { signIn: '/auth/signin' }`。
9. 在 `auth.ts` 中配置 `callbacks.authorized: async ({ auth }) => !!auth`。
10. 创建 `app/api/auth/[...nextauth]/route.ts`，写入 `import { handlers } from "@/auth"` 和 `export const { GET, POST } = handlers`。
11. 在项目根目录创建 `middleware.ts`，写入 `export { auth as middleware } from "@/auth"` 并配置 `config.matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"]`；或用 `auth((req) => { const isLoggedIn = !!req.auth; ... return Response.redirect(new URL('/auth/signin', req.url)) })` 做路径保护。
12. 在 Google Cloud Console 创建/选择项目，启用 Google+ API，创建 OAuth 2.0 Web application 凭据，添加开发重定向 URI `http://localhost:3000/api/auth/callback/google` 和生产重定向 URI `https://yourdomain.com/api/auth/callback/google`，复制 Client ID 和 Client Secret 到 `.env.local`。
13. 安装 Credentials provider 依赖：`pnpm add bcryptjs zod`，`pnpm add -D @types/bcryptjs`。
14. 完整 Credentials 配置：从 `next-auth/providers/credentials`、`zod`、`bcryptjs`、`@/lib/prisma` 导入；在 `authorize` 中用 `credentialsSchema.parse(credentials)`，`prisma.user.findUnique({ where: { email } })` 查用户，`bcrypt.compare(password, user.hashedPassword)` 校验，返回 `id/email/name/image`；设置 `session: { strategy: "jwt" }`。
15. 用户注册 API：创建 `app/api/auth/register/route.ts`，用 `registerSchema` 校验 `email/password/name`，`prisma.user.findUnique` 检查已有用户，返回 400；`bcrypt.hash(password, 10)` 哈希，`prisma.user.create({ data: { email, name, hashedPassword } })`，返回 201，错误返回 500。
16. Server Components 中认证：导入 `auth`，调用 `const session = await auth()`，用 `session?.user` 判断并渲染用户信息。
17. Server Actions 中认证：在函数顶部写 `"use server"`，导入 `auth`、`revalidatePath`、`prisma`，`const session = await auth()`，无 session 抛错，读取 `formData`，`prisma.user.update`，调用 `revalidatePath("/profile")`。
18. Client Components 中认证：创建 `app/providers.tsx`，写 `"use client"`，用 `<SessionProvider>{children}</SessionProvider>`；在 `app/layout.tsx` 中用 `<Providers>{children}</Providers>` 包裹；在客户端组件中用 `useSession`、`signIn`、`signOut`，根据 `status === "loading"`、`!session`、`session` 渲染。
19. 程序化 signIn：在 Server Action 中写 `"use server"`，调用 `await signIn(provider)`、`await signIn("credentials", formData)`、`await signIn("google", { redirectTo: "/dashboard" })`。
20. 登录表单：在 `app/auth/signin/page.tsx` 中，用 `<form action={async () => { "use server"; await signIn("google") }}>` 提供 Google 登录；用 `<form action={async (formData) => { "use server"; await signIn("credentials", formData) }}>` 提供 credentials 登录，输入 `name="email"`、`name="password"`。
21. 退出登录：用 `<form action={async () => { "use server"; await signOut() }}>` 和提交按钮调用 `signOut()`。
22. 配置 Session 策略：在 `auth.ts` 中设置 `session: { strategy: "jwt", maxAge: 30 * 24 * 60 * 60, updateAge: 24 * 60 * 60 }`，或按需改为 `strategy: "database"`。
23. 扩展 Session 类型：用 `declare module "next-auth"` 扩展 `Session`，给 `user` 添加 `id`、`role`；在 `jwt({ token, user })` callback 中把 `user.id`、`user.role` 写入 token；在 `session({ session, token })` callback 中写回 `session.user.id`、`session.user.role`。
24. 实现关键 Callbacks：`signIn` 中可检查 `account?.provider === "google"` 和 `profile?.email_verified === true`；`jwt` 中写入 `token.id`、`token.accessToken = account.access_token`；`session` 中写回 `session.user.id`、`session.accessToken`；`authorized` 中检查 `auth?.user` 和 `/dashboard`；`redirect` 中允许相对 URL 和同源 URL，否则返回 `baseUrl`。
25. 使用 Database Adapter：运行 `pnpm add @auth/prisma-adapter`，在 `auth.ts` 中设置 `adapter: PrismaAdapter(prisma)` 和 `session: { strategy: "database" }`；按原文定义 Prisma schema 的 `User`、`Account`、`Session` 模型、关系、`@unique` 和 `@@unique([provider, providerAccountId])`。
26. 自定义 API 端点：创建 `app/api/user/route.ts`，`const session = await auth()`，无 session 返回 `NextResponse.json({ error: "Unauthorized" }, { status: 401 })`，有 session 返回 `{ user: session.user }`。
27. 受保护路由 helper：创建 `lib/auth-helpers.ts`，实现 `withAuth(handler)`：`const session = await auth()`，无 session 返回 401，否则 `return handler(session)`；在 API route 中调用 `withAuth(async (session) => NextResponse.json({ userId: session.user.id }))`。
28. 安全最佳实践：密码始终用 `bcrypt`、`argon2` 等哈希；生产用 HTTPS；校验 `AUTH_SECRET` 和 provider 凭据；设置 `cookies.sessionToken` 为 `__Secure-next-auth.session-token`，`options` 包含 `httpOnly: true`、`sameSite: 'lax'`、`path: '/'`、`secure: process.env.NODE_ENV === 'production'`；实现 rate limiting；依赖 v5 默认 CSRF；用 `redirect` callback 防 open redirect。
29. Session 管理最佳实践：设置合适 `maxAge`（默认 30 天）；用 `updateAge` 定期刷新；优雅处理 session 过期；敏感应用用 database strategy。
30. Provider 配置最佳实践：Google OAuth 只请求最小必要 scopes；Credentials 始终用 `zod` 等校验输入；多 provider 谨慎允许账号关联；用 callbacks 处理 provider 差异。
31. 性能最佳实践：用 middleware 做路由保护并缓存 session 检查；合适时用 JWT strategy 减少数据库调用；优化数据库查询并加索引；middleware 中用 Edge Runtime。
32. 类型安全最佳实践：用 module augmentation 扩展类型；用 `zod` 做运行时校验；启用 TypeScript strict mode；运行 `pnpm tsc --noEmit` 检查类型错误。
33. 受保护页面 Middleware 模式：`auth((req) => { const isLoggedIn = !!req.auth; const { pathname } = req.nextUrl; const publicRoutes = ['/auth/signin', '/auth/register', '/']; if (publicRoutes.includes(pathname)) return NextResponse.next(); if (!isLoggedIn) { const signInUrl = new URL('/auth/signin', req.url); signInUrl.searchParams.set('callbackUrl', pathname); return NextResponse.redirect(signInUrl); } const adminRoutes = ['/admin']; if (adminRoutes.some(route => pathname.startsWith(route)) && req.auth.user.role !== 'admin') return NextResponse.redirect(new URL('/unauthorized', req.url)); return NextResponse.next(); })`，并设置 matcher 排除 `api`、`_next/static`、`_next/image`、`favicon.ico`。
34. 多 Provider 设置：在 `auth.ts` 中配置 `Google`、`GitHub`、`Credentials`；在 `signIn` callback 中，对于 `account?.provider !== "credentials"`，用 `prisma.user.findUnique({ where: { email: user.email } })` 查已有用户，若存在则 `prisma.account.create({ data: { userId: existingUser.id, type: account.type, provider: account.provider, providerAccountId: account.providerAccountId, access_token: account.access_token, refresh_token: account.refresh_token } })` 关联账号。
35. 自定义登录页：创建 `app/auth/signin/page.tsx`，读取 `searchParams.callbackUrl` 并默认 `/dashboard`；Google 表单调用 `signIn("google", { redirectTo: callbackUrl })`；Credentials 表单调用 `signIn("credentials", { email: formData.get("email"), password: formData.get("password"), redirectTo: callbackUrl })`，异常时 `redirect('/auth/signin?error=CredentialsSignin&callbackUrl=' + callbackUrl)`。
36. 实现 RBAC：创建 `lib/auth-rbac.ts`，定义 `Role = "admin" | "user" | "guest"`，实现 `checkRole(allowedRoles: Role[])`：`const session = await auth()`，无 session 返回 `false`，否则返回 `allowedRoles.includes(session.user.role as Role)`；在 Server Component 无权限时 `redirect("/unauthorized")`，在 Server Action 无权限时 `throw new Error("Unauthorized")`。
37. 从 v4 迁移到 v5：把 `getServerSession(authOptions)` 替换为 `auth()`；把 middleware 中 `withAuth({ callbacks: { authorized: ({ token }) => !!token } })` 替换为 `export { auth as middleware } from "@/auth"`。
38. 故障排除：`AUTH_SECRET` 未设置时生成并写入 `.env.local`；`redirect_uri_mismatch` 时确保 Google Console 重定向 URI 匹配 `http://localhost:3000/api/auth/callback/google`；Session 不持久时检查 `AUTH_URL`、浏览器 cookie 阻止、`sessionToken` cookie；TypeScript session 错误时扩展 `Session`/`JWT` 类型并运行 `pnpm tsc --noEmit`；Credentials 不工作时确保 `session.strategy` 为 `"jwt"`、`authorize` 返回含 `id` 的用户对象、验证 bcrypt 哈希/比对逻辑。
39. 需要时查阅官方资源：Getting Started、Migrating to v5、Google Provider、Credentials Provider、Core API、Session Management、Concepts、官方文档、GitHub、Discord、Examples、Provider List 链接。

适用边界 · 注意事项

• 不适用于非 Next.js 项目；原文按 Next.js App Router 编写。
• Google OAuth 部分需先有 Google Cloud Console 项目和 OAuth 2.0 凭据；没有云账号或不想配置 OAuth 时不要使用该 provider。
• Credentials Provider 生产实现依赖数据库（如 Prisma）和密码哈希库（bcryptjs），无数据库或不想增加依赖时不适用。