如何在 Next.js 中实现身份验证
了解身份验证对于保护应用程序数据至关重要。本页面将指导您使用哪些 React 和 Next.js 功能来实现身份验证。
开始之前,将该过程分解为三个概念会很有帮助
此图显示了使用 React 和 Next.js 功能的身份验证流程

本页面上的示例出于教育目的,介绍了基本的用户名和密码身份验证。虽然您可以实现自定义身份验证解决方案,但为了提高安全性和简化性,我们建议使用身份验证库。这些库提供了身份验证、会话管理和授权的内置解决方案,以及社交登录、多因素身份验证和基于角色的访问控制等附加功能。您可以在身份验证库部分找到列表。
身份验证
注册和登录功能
您可以使用<form>
元素与 React 的服务器操作和useActionState
来捕获用户凭据、验证表单字段并调用身份验证提供程序的 API 或数据库。
由于服务器操作始终在服务器上执行,它们提供了一个安全的处理身份验证逻辑的环境。
以下是实现注册/登录功能的步骤
1. 捕获用户凭据
要捕获用户凭据,请创建一个在提交时调用服务器操作的表单。例如,一个接受用户的姓名、电子邮件和密码的注册表单
import { signup } from '@/app/actions/auth'
export function SignupForm() {
return (
<form action={signup}>
<div>
<label htmlFor="name">Name</label>
<input id="name" name="name" placeholder="Name" />
</div>
<div>
<label htmlFor="email">Email</label>
<input id="email" name="email" type="email" placeholder="Email" />
</div>
<div>
<label htmlFor="password">Password</label>
<input id="password" name="password" type="password" />
</div>
<button type="submit">Sign Up</button>
</form>
)
}
export async function signup(formData: FormData) {}
2. 在服务器上验证表单字段
使用服务器操作在服务器上验证表单字段。如果您的身份验证提供程序不提供表单验证,您可以使用像Zod或Yup这样的模式验证库。
以 Zod 为例,您可以定义一个带有适当错误消息的表单模式
import * as z from 'zod'
export const SignupFormSchema = z.object({
name: z
.string()
.min(2, { error: 'Name must be at least 2 characters long.' })
.trim(),
email: z.email({ error: 'Please enter a valid email.' }).trim(),
password: z
.string()
.min(8, { error: 'Be at least 8 characters long' })
.regex(/[a-zA-Z]/, { error: 'Contain at least one letter.' })
.regex(/[0-9]/, { error: 'Contain at least one number.' })
.regex(/[^a-zA-Z0-9]/, {
error: 'Contain at least one special character.',
})
.trim(),
})
export type FormState =
| {
errors?: {
name?: string[]
email?: string[]
password?: string[]
}
message?: string
}
| undefined
为了防止不必要地调用您的身份验证提供程序的 API 或数据库,如果任何表单字段与定义的模式不匹配,您可以在服务器操作中提早return
。
import { SignupFormSchema, FormState } from '@/app/lib/definitions'
export async function signup(state: FormState, formData: FormData) {
// Validate form fields
const validatedFields = SignupFormSchema.safeParse({
name: formData.get('name'),
email: formData.get('email'),
password: formData.get('password'),
})
// If any form fields are invalid, return early
if (!validatedFields.success) {
return {
errors: validatedFields.error.flatten().fieldErrors,
}
}
// Call the provider or db to create a user...
}
回到您的<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">Name</label>
<input id="name" name="name" placeholder="Name" />
</div>
{state?.errors?.name && <p>{state.errors.name}</p>}
<div>
<label htmlFor="email">Email</label>
<input id="email" name="email" placeholder="Email" />
</div>
{state?.errors?.email && <p>{state.errors.email}</p>}
<div>
<label htmlFor="password">Password</label>
<input id="password" name="password" type="password" />
</div>
{state?.errors?.password && (
<div>
<p>Password must:</p>
<ul>
{state.errors.password.map((error) => (
<li key={error}>- {error}</li>
))}
</ul>
</div>
)}
<button disabled={pending} type="submit">
Sign Up
</button>
</form>
)
}
须知
- 在 React 19 中,
useFormStatus
在返回的对象上包含额外的键,例如 data、method 和 action。如果您未使用 React 19,则只有pending
键可用。- 在修改数据之前,您应始终确保用户也有权执行该操作。请参阅身份验证和授权。
3. 创建用户或检查用户凭据
验证表单字段后,您可以通过调用身份验证提供程序的 API 或数据库来创建新的用户帐户或检查用户是否存在。
继续上一个示例
export async function signup(state: FormState, formData: FormData) {
// 1. Validate form fields
// ...
// 2. Prepare data for insertion into database
const { name, email, password } = validatedFields.data
// e.g. Hash the user's password before storing it
const hashedPassword = await bcrypt.hash(password, 10)
// 3. Insert the user into the database or call an Auth Library's API
const data = await db
.insert(users)
.values({
name,
email,
password: hashedPassword,
})
.returning({ id: users.id })
const user = data[0]
if (!user) {
return {
message: 'An error occurred while creating your account.',
}
}
// TODO:
// 4. Create user session
// 5. Redirect user
}
成功创建用户帐户或验证用户凭据后,您可以创建会话来管理用户的身份验证状态。根据您的会话管理策略,会话可以存储在 Cookie 或数据库中,或两者兼而有之。继续阅读会话管理部分以了解更多信息。
提示
- 上面的示例很冗长,因为它分解了身份验证步骤以用于教育目的。这表明实现您自己的安全解决方案可能会很快变得复杂。考虑使用身份验证库来简化该过程。
- 为了改善用户体验,您可能希望在注册流程中更早地检查重复的电子邮件或用户名。例如,当用户输入用户名或输入字段失去焦点时。这有助于防止不必要的表单提交并向用户提供即时反馈。您可以使用像use-debounce这样的库来防抖请求,以管理这些检查的频率。
会话管理
会话管理确保用户的身份验证状态在请求之间保持不变。它涉及创建、存储、刷新和删除会话或令牌。
会话有两种类型
- 无状态:会话数据(或令牌)存储在浏览器的 Cookie 中。Cookie 随每个请求发送,允许在服务器上验证会话。这种方法更简单,但如果实施不当,安全性可能会降低。
- 数据库:会话数据存储在数据库中,用户的浏览器只接收加密的会话 ID。这种方法更安全,但可能很复杂且使用更多服务器资源。
值得注意: 虽然您可以使用其中一种方法或两种方法,但我们建议使用会话管理库,例如iron-session或Jose。
无状态会话
要创建和管理无状态会话,您需要遵循几个步骤
除了上述内容,请考虑添加功能以在用户再次访问应用程序时更新(或刷新)会话,并在用户注销时删除会话。
值得注意的是: 检查您的身份验证库是否包含会话管理。
1. 生成密钥
有几种方法可以生成用于签名会话的密钥。例如,您可以选择在终端中使用openssl
命令
openssl rand -base64 32
此命令生成一个 32 字符的随机字符串,您可以将其用作密钥并存储在环境变量文件中
SESSION_SECRET=your_secret_key
然后您可以在会话管理逻辑中引用此密钥
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('Failed to verify session')
}
}
提示:
- 负载应包含后续请求中将使用的最少、唯一的用户数据,例如用户 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: '/',
})
}
回到您的服务器操作中,您可以调用createSession()
函数,并使用redirect()
API 将用户重定向到适当的页面
import { createSession } from '@/app/lib/session'
export async function signup(state: FormState, formData: FormData) {
// Previous steps:
// 1. Validate form fields
// 2. Prepare data for insertion into database
// 3. Insert the user into the database or call an Library API
// Current steps:
// 4. Create user session
await createSession(user.id)
// 5. Redirect user
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: '/',
})
}
提示: 检查您的身份验证库是否支持刷新令牌,该令牌可用于延长用户会话。
删除会话
要删除会话,您可以删除 Cookie
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')
}
数据库会话
要创建和管理数据库会话,您需要遵循以下步骤
- 在数据库中创建一个表来存储会话和数据(或检查您的身份验证库是否处理此问题)。
- 实现插入、更新和删除会话的功能
- 在将会话 ID 存储在用户浏览器中之前对其进行加密,并确保数据库和 Cookie 保持同步(这是可选的,但建议用于Proxy中的乐观身份验证检查)。
例如
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. Create a session in the database
const data = await db
.insert(sessions)
.values({
userId: id,
expiresAt,
})
// Return the session ID
.returning({ id: sessions.id })
const sessionId = data[0].id
// 2. Encrypt the session ID
const session = await encrypt({ sessionId, expiresAt })
// 3. Store the session in cookies for optimistic auth checks
const cookieStore = await cookies()
cookieStore.set('session', session, {
httpOnly: true,
secure: true,
expires: expiresAt,
sameSite: 'lax',
path: '/',
})
}
提示:
- 为了加快访问速度,您可以考虑为会话的生命周期添加服务器缓存。您还可以将会话数据保留在主数据库中,并合并数据请求以减少查询次数。
- 您可以选择使用数据库会话来处理更高级的用例,例如跟踪用户上次登录时间,或活动设备数量,或让用户能够注销所有设备。
实现会话管理后,您需要添加授权逻辑来控制用户可以在应用程序中访问和执行的操作。继续阅读授权部分以了解更多信息。
授权
一旦用户通过身份验证并创建了会话,您就可以实施授权来控制用户可以在应用程序中访问和执行的操作。
授权检查主要有两种类型
- 乐观:使用存储在 Cookie 中的会话数据检查用户是否有权访问路由或执行操作。这些检查对于快速操作(例如显示/隐藏 UI 元素或根据权限或角色重定向用户)很有用。
- 安全:使用存储在数据库中的会话数据检查用户是否有权访问路由或执行操作。这些检查更安全,用于需要访问敏感数据或执行敏感操作的场景。
对于这两种情况,我们建议
- 创建数据访问层以集中您的授权逻辑
- 使用数据传输对象(DTO)仅返回必要的数据
- 可选地使用Proxy执行乐观检查。
使用 Proxy 进行乐观检查(可选)
在某些情况下,您可能希望使用Proxy并根据权限重定向用户
- 执行乐观检查。由于 Proxy 在每个路由上运行,因此它是集中重定向逻辑和预过滤未经授权用户的好方法。
- 保护用户之间共享数据的静态路由(例如,付费墙后面的内容)。
但是,由于 Proxy 在每个路由(包括预取路由)上运行,因此仅从 Cookie 读取会话(乐观检查)非常重要,并且避免数据库检查以防止性能问题。
例如
import { NextRequest, NextResponse } from 'next/server'
import { decrypt } from '@/app/lib/session'
import { cookies } from 'next/headers'
// 1. Specify protected and public routes
const protectedRoutes = ['/dashboard']
const publicRoutes = ['/login', '/signup', '/']
export default async function proxy(req: NextRequest) {
// 2. Check if the current route is protected or public
const path = req.nextUrl.pathname
const isProtectedRoute = protectedRoutes.includes(path)
const isPublicRoute = publicRoutes.includes(path)
// 3. Decrypt the session from the cookie
const cookie = (await cookies()).get('session')?.value
const session = await decrypt(cookie)
// 4. Redirect to /login if the user is not authenticated
if (isProtectedRoute && !session?.userId) {
return NextResponse.redirect(new URL('/login', req.nextUrl))
}
// 5. Redirect to /dashboard if the user is authenticated
if (
isPublicRoute &&
session?.userId &&
!req.nextUrl.pathname.startsWith('/dashboard')
) {
return NextResponse.redirect(new URL('/dashboard', req.nextUrl))
}
return NextResponse.next()
}
// Routes Proxy should not run on
export const config = {
matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
}
虽然 Proxy 对初始检查很有用,但它不应该是您保护数据的唯一防线。大多数安全检查应尽可能靠近数据源执行,请参阅数据访问层以获取更多信息。
提示:
- 在 Proxy 中,您还可以使用
req.cookies.get('session').value
读取 Cookie。- Proxy 使用Edge Runtime,请检查您的身份验证库和会话管理库是否兼容。
- 您可以使用 Proxy 中的
matcher
属性来指定 Proxy 应该运行的路由。不过,对于身份验证,建议 Proxy 在所有路由上运行。
创建数据访问层(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 }
})
然后您可以在数据请求、服务器操作、路由处理程序中调用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),
// Explicitly return the columns you need rather than the whole user object
columns: {
id: true,
name: true,
email: true,
},
})
const user = data[0]
return user
} catch (error) {
console.log('Failed to fetch user')
return null
}
})
提示:
使用数据传输对象(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),
// Return specific columns here
})
const user = data[0]
const currentUser = await getUser(user.id)
// Or return only what's specific to the query here
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 async function Dashboard() {
const session = await verifySession()
const userRole = session?.user?.role // Assuming 'role' is part of the session object
if (userRole === 'admin') {
return <AdminDashboard />
} else if (userRole === 'user') {
return <UserDashboard />
} else {
redirect('/login')
}
}
在此示例中,我们使用 DAL 中的verifySession()
函数来检查“管理员”、“用户”和未经授权的角色。此模式确保每个用户仅与适合其角色的组件进行交互。
布局和身份验证检查
由于部分渲染,在布局中进行检查时要谨慎,因为这些布局在导航时不会重新渲染,这意味着用户会话不会在每次路由更改时都进行检查。
相反,您应该在靠近数据源或将有条件渲染的组件处进行检查。
例如,考虑一个共享布局,它获取用户数据并在导航栏中显示用户图像。您不应在布局中进行身份验证检查,而应在布局中获取用户数据(getUser()
)并在 DAL 中进行身份验证检查。
这保证了无论在应用程序的何处调用getUser()
,都会执行身份验证检查,并防止开发人员忘记检查用户是否有权访问数据。
export default async function Layout({
children,
}: {
children: React.ReactNode;
}) {
const user = await getUser();
return (
// ...
)
}
export const getUser = cache(async () => {
const session = await verifySession()
if (!session) return null
// Get user ID from session and fetch data
})
须知
- 在 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
// Return early if user is not authorized to perform the action
if (userRole !== 'admin') {
return null
}
// Proceed with the action for authorized users
}
路由处理程序
像对待面向公众的 API 端点一样对待路由处理程序,并验证用户是否有权访问路由处理程序。
例如
import { verifySession } from '@/app/lib/dal'
export async function GET() {
// User authentication and role verification
const session = await verifySession()
// Check if the user is authenticated
if (!session) {
// User is not authenticated
return new Response(null, { status: 401 })
}
// Check if the user has the 'admin' role
if (session.user.role !== 'admin') {
// User is authenticated but does not have the right permissions
return new Response(null, { status: 403 })
}
// Continue for authorized users
}
上面的示例演示了一个具有两层安全检查的路由处理程序。它首先检查活动会话,然后验证登录用户是否为“管理员”。
上下文提供程序
由于交错,使用上下文提供程序进行身份验证是可行的。但是,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 (
// ...
);
}
如果客户端组件需要会话数据(例如,用于客户端数据获取),请使用 React 的taintUniqueValue
API,以防止敏感会话数据暴露给客户端。
资源
现在您已经了解了 Next.js 中的身份验证,以下是兼容 Next.js 的库和资源,可帮助您实现安全的身份验证和会话管理
身份验证库
会话管理库
延伸阅读
要继续了解身份验证和安全性,请查看以下资源
这有帮助吗?