unauthorized

unauthorized 函数会抛出一个错误，渲染 Next.js 的 401 错误页面。它可用于处理应用程序中的授权错误。您可以通过 unauthorized.js 文件自定义 UI。

要开始使用 unauthorized，请在 next.config.js 文件中启用实验性的 authInterrupts 配置选项：

import type { NextConfig } from 'next'

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

export default nextConfig

module.exports = {
  experimental: {
    authInterrupts: true,
  },
}

unauthorized 可以在服务端组件 (Server Components)、服务端操作 (Server Actions) 和路由处理器 (Route Handlers) 中调用。

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'

export default async function DashboardPage() {
  const session = await verifySession()

  if (!session) {
    unauthorized()
  }

  // 为已认证用户渲染仪表盘
  return (
    <main>
      <h1>欢迎来到仪表盘</h1>
      <p>你好，{session.user.name}。</p>
    </main>
  )
}

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'

export default async function DashboardPage() {
  const session = await verifySession()

  if (!session) {
    unauthorized()
  }

  // 为已认证用户渲染仪表盘
  return (
    <main>
      <h1>欢迎来到仪表盘</h1>
      <p>你好，{session.user.name}。</p>
    </main>
  )
}

须知事项

unauthorized 函数不能在根布局 (root layout) 中调用。

示例

向未认证用户显示登录 UI

您可以使用 unauthorized 函数来显示带有登录界面的 unauthorized.js 文件。

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'

export default async function DashboardPage() {
  const session = await verifySession()

  if (!session) {
    unauthorized()
  }

  return <div>仪表盘</div>
}

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'

export default async function DashboardPage() {
  const session = await verifySession()

  if (!session) {
    unauthorized()
  }

  return <div>仪表盘</div>
}

import Login from '@/app/components/Login'

export default function UnauthorizedPage() {
  return (
    <main>
      <h1>401 - 未授权</h1>
      <p>请登录以访问此页面。</p>
      <Login />
    </main>
  )
}

import Login from '@/app/components/Login'

export default function UnauthorizedPage() {
  return (
    <main>
      <h1>401 - 未授权</h1>
      <p>请登录以访问此页面。</p>
      <Login />
    </main>
  )
}

与服务端操作 (Server Actions) 结合使用

您可以在服务端操作中调用 unauthorized 以确保只有已认证用户才能执行特定的数据变更操作。

'use server'

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
import db from '@/app/lib/db'

export async function updateProfile(data: FormData) {
  const session = await verifySession()

  // 如果用户未认证，返回 401
  if (!session) {
    unauthorized()
  }

  // 继续执行数据变更
  // ...
}

'use server'

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
import db from '@/app/lib/db'

export async function updateProfile(data) {
  const session = await verifySession()

  // 如果用户未认证，返回 401
  if (!session) {
    unauthorized()
  }

  // 继续执行数据变更
  // ...
}

与路由处理器 (Route Handlers) 结合使用

您可以在路由处理器中使用 unauthorized 以确保只有已认证用户才能访问端点。

import { NextRequest, NextResponse } from 'next/server'
import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'

export async function GET(req: NextRequest): Promise<NextResponse> {
  // 验证用户会话
  const session = await verifySession()

  // 如果会话不存在，返回 401 并渲染 unauthorized.tsx
  if (!session) {
    unauthorized()
  }

  // 获取数据
  // ...
}

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'

export async function GET() {
  const session = await verifySession()

  // 如果用户未认证，返回 401 并渲染 unauthorized.tsx
  if (!session) {
    unauthorized()
  }

  // 获取数据
  // ...
}

版本历史

版本	变更内容
`v15.1.0`	引入 `unauthorized` 功能。

unauthorized.js

关于 unauthorized.js 特殊文件的 API 参考文档。