logoNext.js 简体中文
文档博客学习
简介/指南/身份验证

如何在 Next.js 中实现身份验证

理解身份验证机制对于保护应用数据至关重要。本文将指导您使用 React 和 Next.js 特性来实现身份验证功能。

在开始之前，我们可以将整个过程分解为三个核心概念：

  1. 身份验证 (Authentication)：验证用户是否与其声称的身份一致。要求用户通过用户名密码等凭证证明身份。
  2. 会话管理 (Session Management)：跨请求跟踪用户的认证状态。
  3. 授权 (Authorization)：决定用户可以访问哪些路由和数据。

下图展示了使用 React 和 Next.js 特性的身份验证流程：

展示使用 React 和 Next.js 特性的身份验证流程图

本文示例将演示基本的用户名密码验证（出于教学目的）。虽然您可以实现自定义验证方案，但为了更高的安全性和简便性，我们推荐使用身份验证库。这些库提供了开箱即用的解决方案，包括身份验证、会话管理、授权，以及社交登录、多因素认证、基于角色的访问控制等附加功能。您可以在 身份验证库 部分找到相关列表。

身份验证

注册与登录功能

您可以使用 <form> 元素配合 React 的 服务端操作 (Server Actions) 和 useActionState 来捕获用户凭证、验证表单字段并调用身份验证提供商的 API 或数据库。

由于服务端操作始终在服务器端执行，这为处理身份验证逻辑提供了安全环境。

以下是实现注册/登录功能的步骤：

1. 捕获用户凭证

创建表单并在提交时调用服务端操作来捕获用户凭证。例如，一个接收用户名、邮箱和密码的注册表单：

import { signup } from '@/app/actions/auth'

export function SignupForm() {
  return (
    <form action={signup}>
      <div>
        <label htmlFor="name">姓名</label>
        <input id="name" name="name" placeholder="姓名" />
      </div>
      <div>
        <label htmlFor="email">邮箱</label>
        <input id="email" name="email" type="email" placeholder="邮箱" />
      </div>
      <div>
        <label htmlFor="password">密码</label>
        <input id="password" name="password" type="password" />
      </div>
      <button type="submit">注册</button>
    </form>
  )
}
import { signup } from '@/app/actions/auth'

export function SignupForm() {
  return (
    <form action={signup}>
      <div>
        <label htmlFor="name">姓名</label>
        <input id="name" name="name" placeholder="姓名" />
      </div>
      <div>
        <label htmlFor="email">邮箱</label>
        <input id="email" name="email" type="email" placeholder="邮箱" />
      </div>
      <div>
        <label htmlFor="password">密码</label>
        <input id="password" name="password" type="password" />
      </div>
      <button type="submit">注册</button>
    </form>
  )
}
export async function signup(formData: FormData) {}
export async function signup(formData) {}

2. 在服务端验证表单字段

使用服务端操作在服务器上验证表单字段。如果您的身份验证提供商不提供表单验证，可以使用 Zod 或 Yup 等模式验证库。

以 Zod 为例，您可以定义带有错误提示的表单模式：

import { z } from 'zod'

export const SignupFormSchema = z.object({
  name: z
    .string()
    .min(2, { message: '姓名长度至少为2个字符' })
    .trim(),
  email: z.string().email({ message: '请输入有效的邮箱地址' }).trim(),
  password: z
    .string()
    .min(8, { message: '长度至少为8个字符' })
    .regex(/[a-zA-Z]/, { message: '至少包含一个字母' })
    .regex(/[0-9]/, { message: '至少包含一个数字' })
    .regex(/[^a-zA-Z0-9]/, {
      message: '至少包含一个特殊字符',
    })
    .trim(),
})

export type FormState =
  | {
      errors?: {
        name?: string[]
        email?: string[]
        password?: string[]
      }
      message?: string
    }
  | undefined
import { z } from 'zod'

export const SignupFormSchema = z.object({
  name: z
    .string()
    .min(2, { message: '姓名长度至少为2个字符' })
    .trim(),
  email: z.string().email({ message: '请输入有效的邮箱地址' }).trim(),
  password: z
    .string()
    .min(8, { message: '长度至少为8个字符' })
    .regex(/[a-zA-Z]/, { message: '至少包含一个字母' })
    .regex(/[0-9]/, { message: '至少包含一个数字' })
    .regex(/[^a-zA-Z0-9]/, {
      message: '至少包含一个特殊字符',
    })
    .trim(),
})

为避免不必要的身份验证提供商 API 或数据库调用，如果任何表单字段不符合定义的模式，可以在服务端操作中提前 return。

import { SignupFormSchema, FormState } from '@/app/lib/definitions'

export async function signup(state: FormState, formData: FormData) {
  // 验证表单字段
  const validatedFields = SignupFormSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
    password: formData.get('password'),
  })

  // 如果有字段验证失败，提前返回
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    }
  }

  // 调用提供商或数据库创建用户...
}
import { SignupFormSchema } from '@/app/lib/definitions'

export async function signup(state, formData) {
  // 验证表单字段
  const validatedFields = SignupFormSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
    password: formData.get('password'),
  })

  // 如果有字段验证失败，提前返回
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    }
  }

  // 调用提供商或数据库创建用户...
}

回到 <SignupForm /> 组件，您可以使用 React 的 useActionState 钩子在表单提交时显示验证错误：

'use client'

import { signup } from '@/app/actions/auth'
import { useActionState } from 'react'

export default function SignupForm() {
  const [state, action, pending] = useActionState(signup, undefined)

  return (
    <form action={action}>
      <div>
        <label htmlFor="name">姓名</label>
        <input id="name" name="name" placeholder="姓名" />
      </div>
      {state?.errors?.name && <p>{state.errors.name}</p>}

      <div>
        <label htmlFor="email">邮箱</label>
        <input id="email" name="email" placeholder="邮箱" />
      </div>
      {state?.errors?.email && <p>{state.errors.email}</p>}

      <div>
        <label htmlFor="password">密码</label>
        <input id="password" name="password" type="password" />
      </div>
      {state?.errors?.password && (
        <div>
          <p>密码必须：</p>
          <ul>
            {state.errors.password.map((error) => (
              <li key={error}>- {error}</li>
            ))}
          </ul>
        </div>
      )}
      <button disabled={pending} type="submit">
        注册
      </button>
    </form>
  )
}
'use client'

import { signup } from '@/app/actions/auth'
import { useActionState } from 'react'

export default function SignupForm() {
  const [state, action, pending] = useActionState(signup, undefined)

  return (
    <form action={action}>
      <div>
        <label htmlFor="name">姓名</label>
        <input id="name" name="name" placeholder="姓名" />
      </div>
      {state?.errors?.name && <p>{state.errors.name}</p>}

      <div>
        <label htmlFor="email">邮箱</label>
        <input id="email" name="email" placeholder="邮箱" />
      </div>
      {state?.errors?.email && <p>{state.errors.email}</p>}

      <div>
        <label htmlFor="password">密码</label>
        <input id="password" name="password" type="password" />
      </div>
      {state?.errors?.password && (
        <div>
          <p>密码必须：</p>
          <ul>
            {state.errors.password.map((error) => (
              <li key={error}>- {error}</li>
            ))}
          </ul>
        </div>
      )}
      <button disabled={pending} type="submit">
        注册
      </button>
    </form>
  )
}

须知：

  • 在 React 19 中，useFormStatus 返回对象包含额外键值，如 data、method 和 action。如果未使用 React 19，则仅 pending 键可用。
  • 在修改数据前，应始终确保用户已获得授权。参见 身份验证与授权。

3. 创建用户或验证用户凭证

在验证表单字段后，您可以通过调用认证提供商的 API 或数据库来创建新用户账户或检查用户是否存在。

延续之前的示例：

export async function signup(state: FormState, formData: FormData) {
  // 1. 验证表单字段
  // ...

  // 2. 准备插入数据库的数据
  const { name, email, password } = validatedFields.data
  // 例如：在存储前对用户密码进行哈希处理
  const hashedPassword = await bcrypt.hash(password, 10)

  // 3. 将用户插入数据库或调用认证库的 API
  const data = await db
    .insert(users)
    .values({
      name,
      email,
      password: hashedPassword,
    })
    .returning({ id: users.id })

  const user = data[0]

  if (!user) {
    return {
      message: '创建账户时发生错误',
    }
  }

  // 待办事项：
  // 4. 创建用户会话
  // 5. 重定向用户
}
export async function signup(state, formData) {
  // 1. 验证表单字段
  // ...

  // 2. 准备插入数据库的数据
  const { name, email, password } = validatedFields.data
  // 例如：在存储前对用户密码进行哈希处理
  const hashedPassword = await bcrypt.hash(password, 10)

  // 3. 将用户插入数据库或调用库 API
  const data = await db
    .insert(users)
    .values({
      name,
      email,
      password: hashedPassword,
    })
    .returning({ id: users.id })

  const user = data[0]

  if (!user) {
    return {
      message: '创建账户时发生错误',
    }
  }

  // 待办事项：
  // 4. 创建用户会话
  // 5. 重定向用户
}

成功创建用户账户或验证用户凭证后，您可以创建一个会话来管理用户的认证状态。根据会话管理策略的不同，会话可以存储在 cookie 或数据库中，或两者兼有。继续阅读会话管理部分了解更多。

提示：

  • 上面的示例较为详细，因为它为了教育目的分解了认证步骤。这表明实现自己的安全解决方案可能很快变得复杂。考虑使用认证库来简化流程。
  • 为了改善用户体验，您可能希望在注册流程的早期检查重复的电子邮件或用户名。例如，当用户输入用户名或输入字段失去焦点时。这可以帮助防止不必要的表单提交，并为用户提供即时反馈。您可以使用诸如 use-debounce 这样的库来管理这些检查的频率。

会话管理

会话管理确保用户的认证状态在多个请求之间保持。它涉及创建、存储、刷新和删除会话或令牌。

有两种类型的会话：

  1. 无状态会话：会话数据（或令牌）存储在浏览器的 cookie 中。cookie 随每个请求发送，允许在服务器上验证会话。这种方法更简单，但如果实现不当可能不太安全。
  2. 数据库会话：会话数据存储在数据库中，用户的浏览器仅接收加密的会话 ID。这种方法更安全，但可能更复杂并占用更多服务器资源。

须知： 虽然您可以使用其中一种方法或两者兼用，但我们建议使用会话管理库，如 iron-session 或 Jose。

无状态会话

要创建和管理无状态会话，您需要遵循以下步骤：

  1. 生成一个密钥，用于签名会话，并将其存储为环境变量。
  2. 使用会话管理库编写加密/解密会话数据的逻辑。
  3. 使用 Next.js cookies API 管理 cookie。

除了上述内容，还可以考虑添加功能以在用户返回应用程序时更新（或刷新）会话，并在用户注销时删除会话。

须知： 检查您的认证库是否包含会话管理。

1. 生成密钥

有几种方法可以生成用于签名会话的密钥。例如，您可以选择在终端中使用 openssl 命令：

terminal
openssl rand -base64 32

此命令生成一个 32 字符的随机字符串，您可以用作密钥并存储在环境变量文件中：

.env
SESSION_SECRET=your_secret_key

然后，您可以在会话管理逻辑中引用此密钥：

app/lib/session.js
const secretKey = process.env.SESSION_SECRET

2. 加密和解密会话

接下来，您可以使用您首选的会话管理库来加密和解密会话。延续前面的示例，我们将使用 Jose（与 Edge Runtime 兼容）和 React 的 server-only 包，以确保您的会话管理逻辑仅在服务器上执行。

import 'server-only'
import { SignJWT, jwtVerify } from 'jose'
import { SessionPayload } from '@/app/lib/definitions'

const secretKey = process.env.SESSION_SECRET
const encodedKey = new TextEncoder().encode(secretKey)

export async function encrypt(payload: SessionPayload) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(encodedKey)
}

export async function decrypt(session: string | undefined = '') {
  try {
    const { payload } = await jwtVerify(session, encodedKey, {
      algorithms: ['HS256'],
    })
    return payload
  } catch (error) {
    console.log('验证会话失败')
  }
}
import 'server-only'
import { SignJWT, jwtVerify } from 'jose'

const secretKey = process.env.SESSION_SECRET
const encodedKey = new TextEncoder().encode(secretKey)

export async function encrypt(payload) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(encodedKey)
}

export async function decrypt(session) {
  try {
    const { payload } = await jwtVerify(session, encodedKey, {
      algorithms: ['HS256'],
    })
    return payload
  } catch (error) {
    console.log('验证会话失败')
  }
}

提示：

  • 有效载荷应包含在后续请求中使用的最小、唯一的用户数据，例如用户的 ID、角色等。不应包含个人身份信息，如电话号码、电子邮件地址、信用卡信息等，或敏感数据如密码。

3. 设置 cookie（推荐选项）

要将会话存储在 cookie 中，请使用 Next.js cookies API。cookie 应在服务器上设置，并包括以下推荐选项：

  • HttpOnly：防止客户端 JavaScript 访问 cookie。
  • Secure：使用 https 发送 cookie。
  • SameSite：指定 cookie 是否可以与跨站点请求一起发送。
  • Max-Age 或 Expires：在一定时间后删除 cookie。
  • Path：定义 cookie 的 URL 路径。

请参阅 MDN 获取有关这些选项的更多信息。

import 'server-only'
import { cookies } from 'next/headers'

export async function createSession(userId: string) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  const session = await encrypt({ userId, expiresAt })
  const cookieStore = await cookies()

  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}
import 'server-only'
import { cookies } from 'next/headers'

export async function createSession(userId) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  const session = await encrypt({ userId, expiresAt })
  const cookieStore = await cookies()

  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}

回到您的服务器操作中，您可以调用 createSession() 函数，并使用 redirect() API 将用户重定向到适当的页面：

import { createSession } from '@/app/lib/session'

export async function signup(state: FormState, formData: FormData) {
  // 之前的步骤：
  // 1. 验证表单字段
  // 2. 准备插入数据库的数据
  // 3. 将用户插入数据库或调用库 API

  // 当前步骤：
  // 4. 创建用户会话
  await createSession(user.id)
  // 5. 重定向用户
  redirect('/profile')
}
import { createSession } from '@/app/lib/session'

export async function signup(state, formData) {
  // 之前的步骤：
  // 1. 验证表单字段
  // 2. 准备插入数据库的数据
  // 3. 将用户插入数据库或调用库 API

  // 当前步骤：
  // 4. 创建用户会话
  await createSession(user.id)
  // 5. 重定向用户
  redirect('/profile')
}

提示：

  • 应在服务器上设置 cookie 以防止客户端篡改。
  • 🎥 观看：了解更多关于无状态会话和 Next.js 认证的内容 → YouTube (11 分钟)。

更新（或刷新）会话

您还可以延长会话的过期时间。这对于在用户再次访问应用程序时保持其登录状态非常有用。例如：

import 'server-only'
import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'

export async function updateSession() {
  const session = (await cookies()).get('session')?.value
  const payload = await decrypt(session)

  if (!session || !payload) {
    return null
  }

  const expires = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)

  const cookieStore = await cookies()
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expires,
    sameSite: 'lax',
    path: '/',
  })
}
import 'server-only'
import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'

export async function updateSession() {
  const session = (await cookies()).get('session')?.value
  const payload = await decrypt(session)

  if (!session || !payload) {
    return null
  }

  const expires = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)(
    await cookies()
  ).set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expires,
    sameSite: 'lax',
    path: '/',
  })
}

提示： 检查您的认证库是否支持刷新令牌，可用于延长用户的会话。

删除会话

要删除会话，可以删除对应的 cookie：

import 'server-only'
import { cookies } from 'next/headers'

export async function deleteSession() {
  const cookieStore = await cookies()
  cookieStore.delete('session')
}
import 'server-only'
import { cookies } from 'next/headers'

export async function deleteSession() {
  const cookieStore = await cookies()
  cookieStore.delete('session')
}

然后可以在应用中复用 deleteSession() 函数，例如在登出时：

import { cookies } from 'next/headers'
import { deleteSession } from '@/app/lib/session'

export async function logout() {
  await deleteSession()
  redirect('/login')
}
import { cookies } from 'next/headers'
import { deleteSession } from '@/app/lib/session'

export async function logout() {
  await deleteSession()
  redirect('/login')
}

数据库会话

要创建和管理数据库会话，需要遵循以下步骤：

  1. 在数据库中创建表来存储会话数据（或检查您的认证库是否已处理此功能）
  2. 实现插入、更新和删除会话的功能
  3. 将会话 ID 加密后再存储到用户浏览器中，并确保数据库和 cookie 保持同步（这是可选的，但建议用于 中间件 中的乐观认证检查）

例如：

import cookies from 'next/headers'
import { db } from '@/app/lib/db'
import { encrypt } from '@/app/lib/session'

export async function createSession(id: number) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)

  // 1. 在数据库中创建会话
  const data = await db
    .insert(sessions)
    .values({
      userId: id,
      expiresAt,
    })
    // 返回会话 ID
    .returning({ id: sessions.id })

  const sessionId = data[0].id

  // 2. 加密会话 ID
  const session = await encrypt({ sessionId, expiresAt })

  // 3. 将会话存储在 cookie 中以进行乐观认证检查
  const cookieStore = await cookies()
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}
import cookies from 'next/headers'
import { db } from '@/app/lib/db'
import { encrypt } from '@/app/lib/session'

export async function createSession(id) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)

  // 1. 在数据库中创建会话
  const data = await db
    .insert(sessions)
    .values({
      userId: id,
      expiresAt,
    })
    // 返回会话 ID
    .returning({ id: sessions.id })

  const sessionId = data[0].id

  // 2. 加密会话 ID
  const session = await encrypt({ sessionId, expiresAt })

  // 3. 将会话存储在 cookie 中以进行乐观认证检查
  const cookieStore = await cookies()
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}

提示：

  • 为了更快访问，可以考虑为会话生命周期添加服务器缓存。也可以将会话数据保留在主数据库中，并合并数据请求以减少查询次数
  • 对于更高级的用例（如跟踪用户上次登录时间、活跃设备数量或让用户能够注销所有设备），可以选择使用数据库会话

实现会话管理后，需要添加授权逻辑来控制用户可以在应用中访问和执行的内容。继续阅读 授权 部分了解更多。

授权

用户认证并创建会话后，可以实现授权来控制用户在应用中可以访问和执行的内容。

主要有两种授权检查类型：

  1. 乐观检查：使用存储在 cookie 中的会话数据检查用户是否有权访问路由或执行操作。这些检查适用于快速操作，如显示/隐藏 UI 元素或根据权限或角色重定向用户
  2. 安全检查：使用存储在数据库中的会话数据检查用户是否有权访问路由或执行操作。这些检查更安全，用于需要访问敏感数据或操作的情况

对于这两种情况，我们建议：

使用中间件进行乐观检查（可选）

在某些情况下，您可能希望使用 中间件 并根据权限重定向用户：

  • 执行乐观检查。由于中间件在每个路由上运行，这是集中重定向逻辑和预过滤未授权用户的好方法
  • 保护用户之间共享数据的静态路由（如付费内容）

但由于中间件在每个路由上运行（包括 预取 的路由），重要的是仅从 cookie 读取会话（乐观检查），避免数据库检查以防止性能问题。

例如：

import { NextRequest, NextResponse } from 'next/server'
import { decrypt } from '@/app/lib/session'
import { cookies } from 'next/headers'

// 1. 指定受保护和公开路由
const protectedRoutes = ['/dashboard']
const publicRoutes = ['/login', '/signup', '/']

export default async function middleware(req: NextRequest) {
  // 2. 检查当前路由是受保护还是公开
  const path = req.nextUrl.pathname
  const isProtectedRoute = protectedRoutes.includes(path)
  const isPublicRoute = publicRoutes.includes(path)

  // 3. 从 cookie 解密会话
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  // 4. 如果用户未认证，重定向到 /login
  if (isProtectedRoute && !session?.userId) {
    return NextResponse.redirect(new URL('/login', req.nextUrl))
  }

  // 5. 如果用户已认证，重定向到 /dashboard
  if (
    isPublicRoute &&
    session?.userId &&
    !req.nextUrl.pathname.startsWith('/dashboard')
  ) {
    return NextResponse.redirect(new URL('/dashboard', req.nextUrl))
  }

  return NextResponse.next()
}

// 中间件不应运行的路由
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
}
import { NextResponse } from 'next/server'
import { decrypt } from '@/app/lib/session'
import { cookies } from 'next/headers'

// 1. 指定受保护和公开路由
const protectedRoutes = ['/dashboard']
const publicRoutes = ['/login', '/signup', '/']

export default async function middleware(req) {
  // 2. 检查当前路由是受保护还是公开
  const path = req.nextUrl.pathname
  const isProtectedRoute = protectedRoutes.includes(path)
  const isPublicRoute = publicRoutes.includes(path)

  // 3. 从 cookie 解密会话
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  // 5. 如果用户未认证，重定向到 /login
  if (isProtectedRoute && !session?.userId) {
    return NextResponse.redirect(new URL('/login', req.nextUrl))
  }

  // 6. 如果用户已认证，重定向到 /dashboard
  if (
    isPublicRoute &&
    session?.userId &&
    !req.nextUrl.pathname.startsWith('/dashboard')
  ) {
    return NextResponse.redirect(new URL('/dashboard', req.nextUrl))
  }

  return NextResponse.next()
}

// 中间件不应运行的路由
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
}

虽然中间件对初始检查很有用，但它不应该是保护数据的唯一防线。大多数安全检查应尽可能靠近数据源执行，详见 数据访问层。

提示：

  • 在中间件中，也可以使用 req.cookies.get('session').value 读取 cookie
  • 中间件使用 Edge 运行时，请检查您的认证库和会话管理库是否兼容
  • 可以使用中间件中的 matcher 属性指定中间件应运行的路由。但对于认证，建议中间件在所有路由上运行

创建数据访问层 (DAL)

我们建议创建 DAL 来集中数据请求和授权逻辑。

DAL 应包含一个函数，在用户与应用交互时验证用户的会话。至少，该函数应检查会话是否有效，然后重定向或返回进行进一步请求所需的用户信息。

例如，为 DAL 创建一个单独的文件，其中包含 verifySession() 函数。然后使用 React 的 cache API 在 React 渲染过程中记忆化函数的返回值：

import 'server-only'

import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'

export const verifySession = cache(async () => {
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  if (!session?.userId) {
    redirect('/login')
  }

  return { isAuth: true, userId: session.userId }
})
import 'server-only'

import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'

export const verifySession = cache(async () => {
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  if (!session.userId) {
    redirect('/login')
  }

  return { isAuth: true, userId: session.userId }
})

然后可以在数据请求、服务器操作、路由处理程序中调用 verifySession() 函数：

export const getUser = cache(async () => {
  const session = await verifySession()
  if (!session) return null

  try {
    const data = await db.query.users.findMany({
      where: eq(users.id, session.userId),
      // 明确返回所需的列而不是整个用户对象
      columns: {
        id: true,
        name: true,
        email: true,
      },
    })

    const user = data[0]

    return user
  } catch (error) {
    console.log('Failed to fetch user')
    return null
  }
})
export const getUser = cache(async () => {
  const session = await verifySession()
  if (!session) return null

  try {
    const data = await db.query.users.findMany({
      where: eq(users.id, session.userId),
      // 明确返回所需的列而不是整个用户对象
      columns: {
        id: true,
        name: true,
        email: true,
      },
    })

    const user = data[0]

    return user
  } catch (error) {
    console.log('Failed to fetch user')
    return null
  }
})

提示：

  • DAL 可用于保护请求时获取的数据。但对于用户之间共享数据的静态路由，数据将在构建时获取而不是请求时获取。使用 中间件 保护静态路由
  • 对于安全检查，可以通过将会话 ID 与数据库进行比较来检查会话是否有效。使用 React 的 cache 函数避免在渲染过程中对数据库进行不必要的重复请求
  • 您可能希望将相关数据请求合并到一个 JavaScript 类中，该类在任何方法之前运行 verifySession()

使用数据传输对象 (DTO)

在获取数据时，建议只返回应用程序中需要使用的必要数据，而非整个对象。例如，当获取用户数据时，可以仅返回用户ID和姓名，而不是包含密码、电话号码等敏感信息的完整用户对象。

若您无法控制返回的数据结构，或需要避免将完整对象传递给客户端（如在团队协作中），可以采用指定安全字段暴露给客户端的策略。

import 'server-only'
import { getUser } from '@/app/lib/dal'

function canSeeUsername(viewer: User) {
  return true
}

function canSeePhoneNumber(viewer: User, team: string) {
  return viewer.isAdmin || team === viewer.team
}

export async function getProfileDTO(slug: string) {
  const data = await db.query.users.findMany({
    where: eq(users.slug, slug),
    // 在此处返回特定列
  })
  const user = data[0]

  const currentUser = await getUser(user.id)

  // 或在此处仅返回查询所需的特定字段
  return {
    username: canSeeUsername(currentUser) ? user.username : null,
    phonenumber: canSeePhoneNumber(currentUser, user.team)
      ? user.phonenumber
      : null,
  }
}
import 'server-only'
import { getUser } from '@/app/lib/dal'

function canSeeUsername(viewer) {
  return true
}

function canSeePhoneNumber(viewer, team) {
  return viewer.isAdmin || team === viewer.team
}

export async function getProfileDTO(slug) {
  const data = await db.query.users.findMany({
    where: eq(users.slug, slug),
    // 在此处返回特定列
  })
  const user = data[0]

  const currentUser = await getUser(user.id)

  // 或在此处仅返回查询所需的特定字段
  return {
    username: canSeeUsername(currentUser) ? user.username : null,
    phonenumber: canSeePhoneNumber(currentUser, user.team)
      ? user.phonenumber
      : null,
  }
}

通过在数据访问层 (DAL) 集中管理数据请求和授权逻辑，并使用 DTO，可以确保所有数据请求的安全性和一致性，从而更易于维护、审计和调试应用程序。

须知:

  • 定义 DTO 有多种方式，包括使用 toJSON()、如示例中的独立函数或 JavaScript 类。由于这些是 JavaScript 模式而非 React 或 Next.js 特性，建议您研究最适合应用程序的模式。
  • 了解更多安全最佳实践，请参阅 Next.js 安全文章。

服务端组件

在服务端组件中进行权限检查适用于基于角色的访问控制。例如，根据用户角色条件渲染组件：

import { verifySession } from '@/app/lib/dal'

export default function Dashboard() {
  const session = await verifySession()
  const userRole = session?.user?.role // 假设 'role' 是会话对象的一部分

  if (userRole === 'admin') {
    return <AdminDashboard />
  } else if (userRole === 'user') {
    return <UserDashboard />
  } else {
    redirect('/login')
  }
}
import { verifySession } from '@/app/lib/dal'

export default function Dashboard() {
  const session = await verifySession()
  const userRole = session.role // 假设 'role' 是会话对象的一部分

  if (userRole === 'admin') {
    return <AdminDashboard />
  } else if (userRole === 'user') {
    return <UserDashboard />
  } else {
    redirect('/login')
  }
}

在此示例中，我们使用数据访问层中的 verifySession() 函数检查 'admin'、'user' 和未授权角色。这种模式确保每个用户仅与适合其角色的组件交互。

布局与权限检查

由于部分渲染，在布局中进行检查时需谨慎，因为这些检查不会在导航时重新渲染，意味着用户会话不会在每次路由变更时被检查。

相反，应在数据源附近或条件渲染的组件中进行检查。

例如，考虑一个共享布局，它获取用户数据并在导航中显示用户图像。不应在布局中进行权限检查，而应在布局中获取用户数据 (getUser())，并在数据访问层中进行权限检查。

这确保无论何时在应用程序中调用 getUser()，都会执行权限检查，防止开发人员忘记检查用户是否有权访问数据。

export default async function Layout({
  children,
}: {
  children: React.ReactNode;
}) {
  const user = await getUser();

  return (
    // ...
  )
}
export default async function Layout({ children }) {
  const user = await getUser();

  return (
    // ...
  )
}
export const getUser = cache(async () => {
  const session = await verifySession()
  if (!session) return null

  // 从会话中获取用户ID并获取数据
})
export const getUser = cache(async () => {
  const session = await verifySession()
  if (!session) return null

  // 从会话中获取用户ID并获取数据
})

须知:

  • 在单页应用 (SPA) 中，常见的模式是在布局或顶级组件中 return null 如果用户未授权。这种模式不推荐，因为 Next.js 应用程序有多个入口点，无法阻止嵌套路由段和服务端操作被访问。

服务端操作

将服务端操作视为与面向公众的 API 端点相同的安全考虑，并验证用户是否被允许执行变更。

在以下示例中，我们在允许操作继续之前检查用户的角色：

'use server'
import { verifySession } from '@/app/lib/dal'

export async function serverAction(formData: FormData) {
  const session = await verifySession()
  const userRole = session?.user?.role

  // 如果用户未授权执行操作，则提前返回
  if (userRole !== 'admin') {
    return null
  }

  // 为授权用户继续执行操作
}
'use server'
import { verifySession } from '@/app/lib/dal'

export async function serverAction() {
  const session = await verifySession()
  const userRole = session.user.role

  // 如果用户未授权执行操作，则提前返回
  if (userRole !== 'admin') {
    return null
  }

  // 为授权用户继续执行操作
}

路由处理器

将路由处理器视为与面向公众的 API 端点相同的安全考虑，并验证用户是否被允许访问路由处理器。

例如：

import { verifySession } from '@/app/lib/dal'

export async function GET() {
  // 用户认证和角色验证
  const session = await verifySession()

  // 检查用户是否已认证
  if (!session) {
    // 用户未认证
    return new Response(null, { status: 401 })
  }

  // 检查用户是否具有 'admin' 角色
  if (session.user.role !== 'admin') {
    // 用户已认证但没有正确权限
    return new Response(null, { status: 403 })
  }

  // 为授权用户继续执行
}
import { verifySession } from '@/app/lib/dal'

export async function GET() {
  // 用户认证和角色验证
  const session = await verifySession()

  // 检查用户是否已认证
  if (!session) {
    // 用户未认证
    return new Response(null, { status: 401 })
  }

  // 检查用户是否具有 'admin' 角色
  if (session.user.role !== 'admin') {
    // 用户已认证但没有正确权限
    return new Response(null, { status: 403 })
  }

  // 为授权用户继续执行
}

上述示例展示了一个具有两层安全检查的路由处理器。它首先检查活动会话，然后验证登录用户是否为 'admin'。

上下文提供者

由于交错渲染，使用上下文提供者进行认证是可行的。然而，React context 在服务端组件中不受支持，因此仅适用于客户端组件。

这种方式有效，但任何子服务端组件将首先在服务器上渲染，并且无法访问上下文提供者的会话数据：

import { ContextProvider } from 'auth-lib'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ContextProvider>{children}</ContextProvider>
      </body>
    </html>
  )
}
'use client';

import { useSession } from "auth-lib";

export default function Profile() {
  const { userId } = useSession();
  const { data } = useSWR(`/api/user/${userId}`, fetcher)

  return (
    // ...
  );
}
'use client';

import { useSession } from "auth-lib";

export default function Profile() {
  const { userId } = useSession();
  const { data } = useSWR(`/api/user/${userId}`, fetcher)

  return (
    // ...
  );
}

如果客户端组件需要会话数据（例如用于客户端数据获取），可以使用 React 的 taintUniqueValue API 防止敏感会话数据暴露给客户端。

资源

现在您已了解 Next.js 中的认证，以下是帮助您实现安全认证和会话管理的 Next.js 兼容库和资源：

认证库

会话管理库

延伸阅读

要继续学习认证和安全，请查看以下资源：

分析

使用 Next.js Speed Insights 测量和跟踪页面性能

CI 构建缓存

学习如何为 Next.js 构建配置 CI 缓存