NNext.js 中文网 GitHub

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 配置选项:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    authInterrupts: true,
  },
}

export default nextConfig
next.config.js
module.exports = {
  experimental: {
    authInterrupts: true,
  },
}

forbidden 可以在 Server Components、Server Functions 和 Route Handlers 中调用。

app/admin/page.tsx
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 <></>
}
app/admin/page.js
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 会先流式传输:

app/projects/page.tsx
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>
  )
}
app/projects/page.js
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:

app/projects/forbidden.tsx
export default function Forbidden() {
  return (
    <main>
      <h1>403 - Forbidden</h1>
      <p>You don't have access to this page.</p>
    </main>
  )
}
app/projects/forbidden.js
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 根据用户角色限制对某些路由的访问。这可确保已通过身份验证但缺少所需权限的用户无法访问该路由。

app/admin/page.tsx
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>
  )
}
app/admin/page.js
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 仅允许具有特定角色的用户更新敏感数据。

app/actions/update-role.ts
'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()
  }

  // 为已授权用户执行角色更新
  // ...
}
app/actions/update-role.js
'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。
Next.js 中文网