forbidden
experimental
forbidden 函数的 API 参考。
forbidden 函数抛出一个错误,从而渲染 forbidden UI。它可用于处理应用中的授权错误。您可以使用 forbidden.js 文件自定义该 UI。
调用 forbidden() 会抛出一个 NEXT_HTTP_ERROR_FALLBACK;403 错误,并终止抛出该错误的路由段的渲染。Next.js 还会注入一个 <meta name="robots" content="noindex" /> 标签,使该页面不被索引。由于它基于抛出机制工作,因此请在渲染路径中调用它:即在组件中,或在组件 await 的函数中。如果调用遗留在未 await 的 promise 中,则会在无人捕获的地方抛出,且不会渲染 forbidden UI。
要开始使用 forbidden,请在 next.config.js 文件中启用实验性的 authInterrupts 配置选项:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
authInterrupts: true,
},
}
export default nextConfigmodule.exports = {
experimental: {
authInterrupts: true,
},
}forbidden 可以在 Server Components、Server Functions 和 Route Handlers 中调用。
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
export default async function AdminPage() {
const session = await verifySession()
// 检查用户是否具有 'admin' 角色
if (session.role !== 'admin') {
forbidden()
}
// 为已授权用户渲染管理页面
return <></>
}import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
export default async function AdminPage() {
const session = await verifySession()
// 检查用户是否具有 'admin' 角色
if (session.role !== 'admin') {
forbidden()
}
// 为已授权用户渲染管理页面
return <></>
}小知识#
forbidden函数不能在根布局中调用。- 您不需要写
return forbidden()。它会抛出错误(其 TypeScript 返回类型为never),因此执行会停止。在调用外加try/catch会抑制该中断,从而不渲染 forbidden UI。使用unstable_rethrow可让错误继续传播。 - 遗留在未 await 的 promise 中的
forbidden()会在无人捕获的地方抛出,因此不会渲染 forbidden UI。在开发环境中,服务端会记录⨯ unhandledRejection: NEXT_HTTP_ERROR_FALLBACK;403。请始终await可能调用它的函数。
示例#
在流式传输开始后调用 forbidden()#
要在检查会话期间保持页面 shell 和加载 UI 可见,请将角色检查放在加载数据的数据访问层(Data Access Layer)函数中,并在用 <Suspense> 包裹的组件中渲染它。检查在边界内运行,因此在会话解析期间 shell 会先流式传输:
import { Suspense } from 'react'
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
async function getProjects() {
const session = await verifySession()
if (session?.role !== 'admin') {
forbidden()
}
return db.projects.findMany()
}
async function Projects() {
const projects = await getProjects()
return (
<ul>
{projects.map((project) => (
<li key={project.id}>{project.name}</li>
))}
</ul>
)
}
export default function ProjectsPage() {
return (
<main>
<h1>Projects</h1>
<Suspense fallback={<p>Loading...</p>}>
<Projects />
</Suspense>
</main>
)
}import { Suspense } from 'react'
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
async function getProjects() {
const session = await verifySession()
if (session?.role !== 'admin') {
forbidden()
}
return db.projects.findMany()
}
async function Projects() {
const projects = await getProjects()
return (
<ul>
{projects.map((project) => (
<li key={project.id}>{project.name}</li>
))}
</ul>
)
}
export default function ProjectsPage() {
return (
<main>
<h1>Projects</h1>
<Suspense fallback={<p>Loading...</p>}>
<Projects />
</Suspense>
</main>
)
}当会话无访问权限时,getProjects 会调用 forbidden() 并抛出错误。由于这发生在渲染期间,异常会传播到最近的 forbidden 边界,该边界会替代流式传入的内容进行渲染,即使页面 shell 已经发送出去。
在该路由旁添加一个 forbidden.tsx 来定义该 UI:
export default function Forbidden() {
return (
<main>
<h1>403 - Forbidden</h1>
<p>You don't have access to this page.</p>
</main>
)
}export default function Forbidden() {
return (
<main>
<h1>403 - Forbidden</h1>
<p>You don't have access to this page.</p>
</main>
)
}响应在 forbidden() 运行之前就已从 <Suspense> 边界开始流式传输,因此它保持 200 状态。Next.js 会添加一个 noindex 标签。
如果 forbidden() 在响应开始之前运行(包括在预渲染期间),它会返回 403。请参阅状态码。
基于角色的路由保护#
您可以使用 forbidden 根据用户角色限制对某些路由的访问。这可确保已通过身份验证但缺少所需权限的用户无法访问该路由。
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
export default async function AdminPage() {
const session = await verifySession()
// 检查用户是否具有 'admin' 角色
if (session.role !== 'admin') {
forbidden()
}
// 为已授权用户渲染管理页面
return (
<main>
<h1>Admin Dashboard</h1>
<p>Welcome, {session.user.name}!</p>
</main>
)
}import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
export default async function AdminPage() {
const session = await verifySession()
// 检查用户是否具有 'admin' 角色
if (session.role !== 'admin') {
forbidden()
}
// 为已授权用户渲染管理页面
return (
<main>
<h1>Admin Dashboard</h1>
<p>Welcome, {session.user.name}!</p>
</main>
)
}使用 Server Actions 进行变更操作#
在 Server Actions 中实现变更操作时,您可以使用 forbidden 仅允许具有特定角色的用户更新敏感数据。
'use server'
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
import db from '@/app/lib/db'
export async function updateRole(formData: FormData) {
const session = await verifySession()
// 确保只有管理员可以更新角色
if (session.role !== 'admin') {
forbidden()
}
// 为已授权用户执行角色更新
// ...
}'use server'
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
import db from '@/app/lib/db'
export async function updateRole(formData) {
const session = await verifySession()
// 确保只有管理员可以更新角色
if (session.role !== 'admin') {
forbidden()
}
// 为已授权用户执行角色更新
// ...
}版本历史#
| 版本 | 变更 |
|---|---|
v15.1.0 | 引入 forbidden。 |