permanentRedirect#

• 상위 메뉴: Functions
• 전체 목차: Next.js 학습 문서

학습 목표#

• permanentRedirect 함수를 사용하여 리소스를 영구적으로 새 URL로 이전(SEO 인덱싱 이전)하는 방법을 익힌다.
• 임시 리다이렉트(redirect, 307)와 영구 리다이렉트(permanentRedirect, 308)의 차이점 및 사용 시나리오를 구분한다.
• try/catch 블록 외부에서 호출해야 하는 에러 제어 흐름 특성을 이해한다.

핵심 개념 및 설명#

permanentRedirect 함수는 사용자를 다른 URL로 영구 리다이렉트(HTTP 308 Permanent Redirect)시키는 Server Component 및 Route Handler 전용 함수다. 주로 엔티티의 정규 URL이 영구적으로 변경되었을 때(예: 사용자 프로필 URL 변경) 사용된다.

import { permanentRedirect } from 'next/navigation'

async function fetchUser(id: string) {
  const res = await fetch(`https://api.example.com/user/${id}`)
  if (!res.ok) {
    permanentRedirect('/users')
  }
  return res.json()
}

export default async function UserProfile({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const user = await fetchUser(id)
  return <div>{user.username}</div>
}

매개변수 (Parameters)#

permanentRedirect(url, type)

1. `url`: 영구 이전할 대상 경로 문자열 (상대 경로 /users 또는 절대 URL https://example.com/users)
2. `type` (선택 사항): Server Action 내에서의 히스토리 제어 ('replace' 기본값, 'push')

307 vs 308 상태 코드 비교#

주의사항: try/catch 블록 분리#

permanentRedirect() 역시 내부적으로 NEXT_REDIRECT 에러를 던지므로 try/catch 블록 외부에서 호출해야 한다.

'use server'

import { permanentRedirect } from 'next/navigation'

export async function updateUsername(formData: FormData) {
  let newSlug = ''
  try {
    newSlug = await db.updateUser({ username: formData.get('username') })
  } catch (error) {
    return { error: '업데이트 실패' }
  }

  // 성공 후 외부에서 호출
  permanentRedirect(`/profile/${newSlug}`)
}

Version History#

예제 및 데모 설계#

• 사용자 계정 변경 시 permanentRedirect('/profile/new-username')를 트리거하고 네트워크 탭에서 308 Permanent Redirect 상태 코드가 반환되는지 확인한다.

연습 문제#

1. 리소스의 URL이 영구적으로 이전되어 검색 엔진의 색인 주소를 새 URL로 갱신하고자 할 때 사용해야 하는 함수와 상태 코드는?

• A. redirect(), 307
• B. permanentRedirect(), 308
• C. redirect(), 302
• D. notFound(), 404

챕터 요약#

• permanentRedirect는 308 상태 코드로 영구 리다이렉트를 수행하여 검색 엔진 색인을 갱신한다.
• redirect(307)와 마찬가지로 내부 특수 에러를 발생시키므로 try/catch 블록 외부에서 호출한다.