NNext.js 中文网 GitHub

redirect

redirect 函数的 API 参考。

redirect 函数允许您将用户重定向到另一个 URL。redirect 可在服务器组件和客户端组件、Route Handler 和 Server Function 的渲染过程中使用。

在流式上下文中使用时,它会插入一个 meta 标签,在客户端发出重定向。在 Server Action 中,当 JavaScript 可用时,redirect 会执行客户端导航。对于渐进增强的表单提交,它会返回 303 HTTP 重定向响应。否则,返回 307 HTTP 重定向响应。

如果资源不存在,您可以改用 notFound 函数。

参考#

参数#

redirect 函数接受两个参数:

js
redirect(path, type)
参数类型描述
pathstring要重定向到的 URL。可以是相对路径或绝对路径。
type'replace'(默认)或 'push'(Server Actions 中的默认值)要执行的重定向类型。

默认情况下,redirect 在 Server Action 中使用 push(向浏览器历史记录栈添加新条目),在其他情况下使用 replace(替换浏览器历史记录栈中的当前 URL)。您可以通过指定 type 参数来覆盖此行为。

RedirectType 对象包含 type 参数的可用选项。

ts
import { redirect, RedirectType } from 'next/navigation'

redirect('/redirect-to', RedirectType.replace)
// 或
redirect('/redirect-to', RedirectType.push)

type 参数在服务器组件中使用时不起作用。

返回值#

redirect 不返回任何值。

行为#

  • 在 Server Action 和 Route Handler 中,使用 try/catch 语句时,redirect 应在 try 块之外调用。
  • 如果您希望返回 308(永久)HTTP 重定向而不是 307(临时)重定向,可以改用 permanentRedirect 函数。
  • redirect 会抛出错误,因此使用 try/catch 语句时,它应在 try 块之外调用。
  • redirect 可以在客户端组件的渲染过程中调用,但不能在事件处理程序中调用。您可以改用 useRouter Hook。
  • redirect 也接受绝对 URL,可用于重定向到外部链接。
  • 如果您想在渲染过程之前重定向,请使用 next.config.js 或 Proxy。

示例#

服务器组件#

调用 redirect() 函数会抛出 NEXT_REDIRECT 错误,并终止抛出该错误的路由片段的渲染。

app/team/[id]/page.tsx
import { redirect } from 'next/navigation'

async function fetchTeam(id: string) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const team = await fetchTeam(id)

  if (!team) {
    redirect('/login')
  }

  // ...
}
app/team/[id]/page.js
import { redirect } from 'next/navigation'

async function fetchTeam(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({ params }) {
  const { id } = await params
  const team = await fetchTeam(id)

  if (!team) {
    redirect('/login')
  }

  // ...
}

小知识:redirect 不需要您使用 return redirect(),因为它使用 TypeScript 的 never 类型。

客户端组件#

redirect 可以直接在客户端组件中使用。

components/client-redirect.tsx
'use client'

import { redirect, usePathname } from 'next/navigation'

export function ClientRedirect() {
  const pathname = usePathname()

  if (pathname.startsWith('/admin') && !pathname.includes('/login')) {
    redirect('/admin/login')
  }

  return <div>Login Page</div>
}
components/client-redirect.jsx
'use client'

import { redirect, usePathname } from 'next/navigation'

export function ClientRedirect() {
  const pathname = usePathname()

  if (pathname.startsWith('/admin') && !pathname.includes('/login')) {
    redirect('/admin/login')
  }

  return <div>Login Page</div>
}

小知识:在初始页面加载期间,当在客户端组件中使用 redirect 并进行服务器端渲染(SSR)时,它将执行服务器端重定向。

redirect 可以通过 Server Action 在客户端组件中使用。如果您需要使用事件处理程序来重定向用户,可以使用 useRouter Hook。

app/client-redirect.tsx
'use client'

import { navigate } from './actions'

export function ClientRedirect() {
  return (
    <form action={navigate}>
      <input type="text" name="id" />
      <button>Submit</button>
    </form>
  )
}
app/client-redirect.jsx
'use client'

import { navigate } from './actions'

export function ClientRedirect() {
  return (
    <form action={navigate}>
      <input type="text" name="id" />
      <button>Submit</button>
    </form>
  )
}
app/actions.ts
'use server'

import { redirect } from 'next/navigation'

export async function navigate(data: FormData) {
  redirect(`/posts/${data.get('id')}`)
}
app/actions.js
'use server'

import { redirect } from 'next/navigation'

export async function navigate(data) {
  redirect(`/posts/${data.get('id')}`)
}

FAQ#

为什么 redirect 使用 307 和 308?#

使用 redirect() 时,您可能会注意到使用的状态码是 307 表示临时重定向,308 表示永久重定向。传统上,302 用于临时重定向,301 用于永久重定向,但许多浏览器在使用 302 时会更改重定向的请求方法,将 POST 请求改为 GET 请求,而不管原始请求方法是什么。

以从 /users 重定向到 /people 为例,如果您向 /users 发出 POST 请求以创建新用户,并且遵循 302 临时重定向,则请求方法将从 POST 更改为 GET。这没有意义,因为要创建新用户,您应该向 /people 发出 POST 请求,而不是 GET 请求。

307 状态码的引入意味着请求方法会保留为 POST。

  • 302 - 临时重定向,会将请求方法从 POST 更改为 GET
  • 307 - 临时重定向,会保留请求方法为 POST

redirect() 方法默认使用 307,而不是 302 临时重定向,这意味着请求方法会被保留。Server Action 表单提交是一个例外:它们使用 303 响应,以便浏览器使用 GET 请求跟随重定向。当 JavaScript 可用时,Server Action 会执行客户端导航,而不是 HTTP 重定向。

有关 HTTP 重定向的了解更多信息。

版本历史#

版本变更
v13.0.0引入 redirect。
Next.js 中文网