title: revalidatePath
description: revalidatePath 함수에 대한 API 참조 문서입니다.
url: "https://nextjs.org/docs/app/api-reference/functions/revalidatePath"
version: 16.1.6
lastUpdated: 2026-02-27
prerequisites:
- "API 참조: https://nextjs.org/docs/app/api-reference"
- "함수들: https://nextjs.org/docs/app/api-reference/functions"
revalidatePath를 사용하면 특정 경로에 대해 필요할 때(on-demand) 캐시된 데이터를 무효화(invalidate)할 수 있어요.
💡 강사의 팁!
여기서 '무효화(invalidate)'한다는 건, 기존에 저장해둔 낡은 캐시 데이터를 버리고 다음 요청 때 최신 데이터를 새로 가져오도록 서버에 알려주는 과정이라고 생각하시면 이해하기 쉬워요! 사용자가 게시글을 수정했을 때 바로 화면에 반영되게 하려면 꼭 필요한 기능이랍니다.
사용법 (Usage)
revalidatePath는 서버 함수(Server Functions)나 라우트 핸들러(Route Handlers) 안에서 호출할 수 있습니다.
클라이언트 컴포넌트(Client Components)나 프록시(Proxy)에서는 호출할 수 없어요. 왜냐하면 이 함수는 오직 서버 환경에서만 동작하도록 설계되었거든요!
알아두면 좋은 점 (Good to know):
- 서버 함수 (Server Functions): 변경된 경로를 사용자가 보고 있다면 UI를 즉시 업데이트해줍니다. 현재는 다시 접근할 때 이전에 방문했던 모든 페이지가 새로고침되는 현상도 발생하는데요, 이건 일시적인 동작이라 향후에는 딱 지정한 경로에만 적용되도록 업데이트될 예정이에요.
- 라우트 핸들러 (Route Handlers): 해당 경로를 '재검증해야 함' 상태로 표시(mark)해둡니다. 실제 재검증은 지정된 경로를 다음 번에 방문할 때 이루어져요. 즉, 동적 라우트 세그먼트를 넣어서
revalidatePath를 호출한다고 해서 당장 수많은 재검증 작업이 한꺼번에 터지는 건 아니라는 뜻이죠. 무효화 처리는 오직 그 경로에 누군가 다시 방문할 때만 발생한답니다.
파라미터 (Parameters)
revalidatePath(path: string, type?: 'page' | 'layout'): void;path: 재검증하고 싶은 데이터에 해당하는 라우트 패턴(예:/product/[slug])이나 특정 URL(예:/product/123)을 나타내는 문자열입니다. 여기에/page나/layout을 직접 뒤에 붙이지 마시고, 대신 두 번째 파라미터인type을 사용해주세요. 이 문자열은 최대 1024자를 넘을 수 없으며, 대소문자를 구분(case-sensitive)합니다.type: (선택 사항) 재검증할 경로의 타입을 변경하는'page'또는'layout'문자열입니다. 만약path에 동적 세그먼트(예:/product/[slug])가 포함되어 있다면 이type파라미터는 필수로 넣어주셔야 해요. 반대로path가 딱 떨어지는 특정 URL(예:/product/1)이라면type파라미터는 생략하시면 됩니다.
단일 페이지만 새로고침하고 싶다면 특정 URL을 사용하시고, 여러 개의 URL을 한꺼번에 새로고침하고 싶다면 라우트 패턴과 type을 함께 사용하세요.
반환값 (Returns)
revalidatePath는 아무 값도 반환하지 않습니다 (void).
무엇을 무효화할 수 있나요? (What can be invalidated)
path 파라미터는 페이지, 레이아웃, 혹은 라우트 핸들러를 가리킬 수 있어요:
- 페이지 (Pages): 특정 페이지 자체를 무효화합니다.
- 레이아웃 (Layouts): 해당 세그먼트의 레이아웃(
layout.tsx), 그 아래에 중첩된 모든 하위 레이아웃, 그리고 그 아래의 모든 하위 페이지들까지 전부 무효화합니다. - 라우트 핸들러 (Route Handlers): 라우트 핸들러 안에서 접근했던 데이터 캐시(Data Cache) 항목들을 무효화합니다. 예를 들어
revalidatePath("/api/data")를 호출하면 아래에 작성된 GET 핸들러가 무효화되는 식이죠.
export async function GET() {
const data = await fetch('[https://api.vercel.app/blog](https://api.vercel.app/blog)', {
cache: 'force-cache',
})
return Response.json(await data.json())
}💡 강사의 팁!
레이아웃을 무효화할 때는 주의하셔야 해요! 레이아웃 레벨에서revalidatePath를 실행하면 그 하위에 있는 수많은 페이지들의 캐시가 한꺼번에 날아가기 때문에, 꼭 필요할 때만 범위(type='layout')를 넓게 잡는 것이 서버 리소스 관리에 좋습니다.
revalidateTag 및 updateTag와의 관계
revalidatePath, revalidateTag, 그리고 updateTag는 각기 다른 목적을 가지고 있어요:
revalidatePath: 특정 페이지나 레이아웃의 '경로(path)'를 무효화합니다.revalidateTag: 특정 태그가 붙은 데이터를 stale(오래된 것) 상태로 표시해요. 이 태그를 사용하는 모든 페이지에 걸쳐서 일괄 적용되죠.updateTag: 특정 태그가 붙은 데이터를 즉시 만료시킵니다. 이 역시 해당 태그를 쓰는 모든 페이지에 적용됩니다.
revalidatePath를 호출하면, 지정된 경로만 다음 방문 시 새로운 데이터를 가져오게 돼요. 동일한 데이터를 사용하더라도 경로가 다른 페이지들은, 그 특정 태그들이 직접 재검증되기 전까지는 계속해서 기존의 캐시된 데이터를 보여주게 됩니다. 아래 코드를 볼까요?
// Page A: /blog
const posts = await fetch('[https://api.vercel.app/blog](https://api.vercel.app/blog)', {
next: { tags: ['posts'] },
})
// Page B: /dashboard
const recentPosts = await fetch('[https://api.vercel.app/blog?limit=5](https://api.vercel.app/blog?limit=5)', {
next: { tags: ['posts'] },
})위 상태에서 revalidatePath('/blog')를 호출하면 다음과 같은 일이 벌어집니다:
- 페이지 A (/blog): 신선한 새 데이터를 보여줍니다. (페이지가 다시 렌더링되었기 때문이죠)
- 페이지 B (/dashboard): 여전히 예전(stale) 데이터를 보여줍니다. ('posts'라는 캐시 태그 자체가 무효화된 건 아니니까요!)
💡 강사의 팁!
"이 주소 화면 다시 그려!" 라고 하고 싶으면revalidatePath를, "이 데이터('posts') 들어간 화면들 다 업데이트해!" 라고 하고 싶으면revalidateTag나updateTag를 쓴다고 기억해두시면 완벽합니다!
revalidateTag와 updateTag의 차이점에 대해서도 한 번 알아보시는 걸 추천해요.
재검증 유틸리티 만들기 (Building revalidation utilities)
revalidatePath와 updateTag는 서로 보완적인 역할을 하는 기본 기능(primitives)이라서, 애플리케이션 전체의 데이터 일관성을 빈틈없이 유지하기 위해 유틸리티 함수 안에서 함께 사용하는 경우가 많습니다:
'use server'
import { revalidatePath, updateTag } from 'next/cache'
export async function updatePost() {
await updatePostInDatabase()
revalidatePath('/blog') // 블로그 페이지 새로고침
updateTag('posts') // 'posts' 태그를 사용하는 모든 페이지 새로고침
}이런 패턴을 활용하면 특정 페이지는 물론이고, 동일한 데이터를 사용하는 다른 모든 페이지들까지 항상 일관된 최신 상태를 유지할 수 있답니다.
예제 (Examples)
특정 URL 재검증하기 (Revalidating a specific URL)
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/post-1')이렇게 하면 다음 번 페이지 방문 시 재검증할 수 있도록 딱 하나의 특정 URL만 무효화합니다.
페이지 경로 재검증하기 (Revalidating a Page path)
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'page')
// 또는 라우트 그룹과 함께 사용하는 경우
revalidatePath('/(main)/blog/[slug]', 'page')이 코드는 제공된 page 파일 구조와 일치하는 모든 URL을 무효화해서 다음 방문 시 재검증하도록 만들어요. 단, 특정 페이지 아래에 있는 하위 페이지들은 무효화하지 않는다는 점 주의하세요! 예를 들어, /blog/[slug]를 재검증한다고 해서 /blog/[slug]/[author] 경로까지 무효화되지는 않아요.
레이아웃 경로 재검증하기 (Revalidating a Layout path)
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'layout')
// 또는 라우트 그룹과 함께 사용하는 경우
revalidatePath('/(main)/post/[slug]', 'layout')이 코드는 제공된 layout 파일 구조와 일치하는 모든 URL을 무효화합니다. 즉, 동일한 레이아웃을 공유하는 그 아래의 하위 페이지들까지 모조리 무효화되고 다음 방문 시 재검증되게 만들어요. 위 예시의 경우라면 /blog/[slug]/[another] 같은 하위 경로도 다음 방문 시 같이 무효화되고 재검증된다는 뜻이죠.
모든 데이터 재검증하기 (Revalidating all data)
import { revalidatePath } from 'next/cache'
revalidatePath('/', 'layout')이렇게 하면 클라이언트 측 라우터 캐시(Client-side Router Cache)를 싹 비우고(purge), 다음 페이지 방문 시 재검증할 수 있도록 데이터 캐시(Data Cache)도 무효화합니다. (사이트 전체를 새로고침하는 것과 비슷한 강력한 효과가 있어요!)
서버 함수 예제 (Server Function)
'use server'
import { revalidatePath } from 'next/cache'
export default async function submit() {
await submitForm()
revalidatePath('/')
}라우트 핸들러 예제 (Route Handler)
import { revalidatePath } from 'next/cache'
import type { NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const path = request.nextUrl.searchParams.get('path')
if (path) {
revalidatePath(path)
return Response.json({ revalidated: true, now: Date.now() })
}
return Response.json({
revalidated: false,
now: Date.now(),
message: 'Missing path to revalidate',
})
}import { revalidatePath } from 'next/cache'
export async function GET(request) {
const path = request.nextUrl.searchParams.get('path')
if (path) {
revalidatePath(path)
return Response.json({ revalidated: true, now: Date.now() })
}
return Response.json({
revalidated: false,
now: Date.now(),
message: 'Missing path to revalidate',
})
}모든 문서의 의미론적 개요(semantic overview)를 보시려면 https://nextjs.org/docs/sitemap.md 를 확인해주세요.
사용 가능한 모든 문서의 인덱스(index)를 보시려면 https://nextjs.org/docs/llms.txt 를 확인해주세요.
