title: updateTag (태그 업데이트)
description: updateTag 함수에 대한 API 참조(Reference) 문서입니다.
url: "https://nextjs.org/docs/app/api-reference/functions/updateTag"
version: 16.1.6
lastUpdated: 2026-02-27
prerequisites:
- "API Reference: https://nextjs.org/docs/app/api-reference"
- "Functions: https://nextjs.org/docs/app/api-reference/functions"
안녕하세요! 프론트엔드 개발자 여러분. 오늘은 Next.js에서 데이터를 다룰 때 정말 자주 마주치게 될 updateTag 함수에 대해 함께 공부해 보겠습니다. 공식 문서를 바탕으로, 여러분이 실무에서 헷갈리지 않도록 제 경험과 팁을 팍팍 담아 설명해 드릴게요. 자, 시작해 볼까요?
updateTag 함수를 사용하면 서버 액션(Server Actions) 내부에서 특정 캐시 태그와 연결된 캐시된 데이터를 우리가 원할 때 즉각적으로 업데이트(무효화)할 수 있어요.
이 함수는 특히 "내가 쓴 글 바로 읽기(read-your-own-writes)" 시나리오를 위해 특별히 설계되었습니다. 사용자가 어떤 변경을 가했을 때(예를 들어, 새 게시글을 작성하거나 프로필을 수정했을 때), 화면에 낡은 데이터(stale data)가 아니라 방금 수정한 변경 사항이 즉시 보이도록 만들어주는 핵심적인 역할을 하죠.
🧑🏫 강사의 보충 설명:
Next.js의 강력한 캐싱 시스템은 웹사이트를 정말 빠르게 만들어주지만, 양날의 검이 될 수 있어요. "분명히 글을 썼는데 왜 목록에 안 나오지?" 하는 당황스러운 경험, 다들 한 번쯤 겪어보셨을 거예요. 브라우저나 서버가 이전 데이터를 기억하고 있기 때문이죠. 이럴 때updateTag를 호출해서 "이 데이터는 이제 새로고침해야 해!"라고 알려주는 겁니다.
이해를 돕기 위해 캐싱이 어떻게 동작하는지 다이어그램으로 살펴볼게요.
사용법 (Usage)
updateTag는 오직 서버 액션(Server Actions) 내부에서만 호출할 수 있습니다. Route Handlers(API 라우트), Client Components(클라이언트 컴포넌트), 또는 다른 어떤 컨텍스트에서도 절대 사용할 수 없어요.
만약 Route Handlers나 다른 컨텍스트에서 캐시 태그를 무효화해야 한다면, 이 함수 대신 revalidateTag를 사용하셔야 합니다.
💡 알아두면 좋은 점 (Good to know): >
updateTag는 지정된 태그의 캐시된 데이터를 즉시 만료시킵니다. 따라서 다음 요청이 들어오면, 서버는 캐시에서 낡은 콘텐츠를 바로 꺼내주지 않고 새롭고 신선한 데이터를 가져올 때까지 기다립니다. 덕분에 사용자는 자신이 수정한 내용을 새로고침 없이도 즉시 확인할 수 있게 되는 거죠.
매개변수 (Parameters)
이 함수는 어떻게 생겼는지 볼까요?
updateTag(tag: string): void;tag: 여러분이 업데이트(무효화)하고 싶은 데이터와 연결된 캐시 태그를 나타내는 문자열(string)입니다. 길이는 최대 256자를 초과할 수 없으며, 대소문자를 엄격하게 구분합니다.
물론, 이 함수를 쓰려면 캐시된 데이터에 먼저 태그가 할당되어 있어야겠죠? 태그를 부여하는 방법은 다음 두 가지가 있습니다.
- 외부 API 요청 캐싱:
fetch함수를 사용할 때next.tags옵션을 사용하여 태그를 달아줄 수 있습니다.
fetch(url, { next: { tags: ['posts'] } })- 내부 함수/컴포넌트 캐싱:
'use cache'지시어(directive)와 함께 캐시되는 함수나 컴포넌트 내부에서cacheTag를 사용할 수 있습니다.
import { cacheTag } from 'next/cache'
async function getData() {
'use cache'
cacheTag('posts')
// ...
}🧑🏫 강사의 실무 팁!
태그 이름을 지을 때는 일관성 있는 규칙(Naming Convention)을 정하는 게 정말 중요해요!
전체 게시글 목록에 영향을 준다면'posts'처럼 복수형을 쓰고, 특정 게시글 하나만 수정한다면`post-${id}`처럼 고유한 ID를 섞어서 쓰는 패턴을 추천합니다. 그래야 불필요하게 전체 캐시를 날려버리는 일을 막고 서버 비용도 절약할 수 있거든요.
반환값 (Returns)
updateTag는 아무 값도 반환하지 않습니다. (즉, 반환 타입이 void 입니다.)
revalidateTag와의 차이점 (Differences from revalidateTag)
updateTag와 revalidateTag 두 함수 모두 캐시된 데이터를 무효화한다는 점은 같지만, 쓰임새와 목적이 완전히 다릅니다. 이 부분을 헷갈리시면 실무에서 버그 잡느라 밤을 새울 수도 있어요! 한눈에 보기 쉽게 표로 정리해 드릴게요.
| 특징 | updateTag | revalidateTag |
|---|---|---|
| 사용 가능 위치 | 서버 액션(Server Actions)에서만 가능 | 서버 액션, 라우트 핸들러(Route Handlers) 모두 가능 |
| 작동 방식 | 다음 요청은 무조건 신선한 데이터를 가져올 때까지 대기 (낡은 데이터 노출 없음) | profile="max" 사용 시: 백그라운드에서 데이터를 가져오는 동안 일단 기존 캐시 데이터(stale data)를 먼저 보여줌 (Stale-While-Revalidate 방식) |
| 설정 옵션 | 즉각적인 무효화만 지원 | 커스텀 프로필 설정으로 고급 캐시 수명 제어 가능 (프로필 생략 시 updateTag와 동일한 기존 방식(legacy)으로 동작) |
| 주요 목적 | "내가 쓴 글 바로 읽기" (사용자의 데이터 변경 즉시 반영) | 데이터의 주기적 갱신 및 백그라운드 업데이트 (사용자 경험 저하 방지) |
🧑🏫 강사의 핵심 요약:
사용자가 "내 정보 수정"을 눌렀는데 아주 잠깐이라도 예전 정보가 보이면 어떨까요? "어? 수정 안 됐나?" 하고 새로고침을 또 누르겠죠. 이럴 때는 무조건 화면을 잠깐 멈추더라도 최신 데이터를 확실히 가져오는updateTag를 써야 합니다.
반면에, 쇼핑몰 메인 화면의 '오늘의 추천 상품' 같은 건 어떨까요? 추천 상품이 1~2초 늦게 바뀐다고 큰일 나진 않잖아요? 이런 건 백그라운드에서 조용히 데이터를 업데이트하는revalidateTag를 써서 사용자에게는 항상 빠르게(캐시된) 화면을 보여주는 게 좋습니다.
예제 (Examples)
이제 코드를 보면서 눈에 익혀볼까요?
"내가 쓴 글 바로 읽기"가 적용된 서버 액션 (Server Action with Read-Your-Own-Writes)
아래 코드는 게시글을 작성하고, 캐시를 지우고, 새 게시글 페이지로 넘어가는 완벽한 흐름을 보여줍니다.
'use server'
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
const title = formData.get('title')
const content = formData.get('content')
// 데이터베이스에 새 게시글을 생성합니다
const post = await db.post.create({
data: { title, content },
})
// 새 게시글이 즉시 보이도록 캐시 태그들을 무효화합니다.
// 'posts' 태그: 게시글 목록을 보여주는 모든 페이지에 영향을 줍니다.
updateTag('posts')
// 'post-{id}' 태그: 개별 게시글 상세 페이지에 영향을 줍니다.
updateTag(`post-${post.id}`)
// 방금 작성한 새 게시글 페이지로 리다이렉트합니다 - 사용자는 캐시된 데이터가 아닌 신선한 데이터를 보게 됩니다.
redirect(`/posts/${post.id}`)
}'use server'
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData) {
const title = formData.get('title')
const content = formData.get('content')
// 데이터베이스에 새 게시글을 생성합니다
const post = await db.post.create({
data: { title, content },
})
// 새 게시글이 즉시 보이도록 캐시 태그들을 무효화합니다.
// 'posts' 태그: 게시글 목록을 보여주는 모든 페이지에 영향을 줍니다.
updateTag('posts')
// 'post-{id}' 태그: 개별 게시글 상세 페이지에 영향을 줍니다.
updateTag(`post-${post.id}`)
// 방금 작성한 새 게시글 페이지로 리다이렉트합니다 - 사용자는 캐시된 데이터가 아닌 신선한 데이터를 보게 됩니다.
redirect(`/posts/${post.id}`)
}서버 액션 외부에서 사용할 때 발생하는 에러 (Error when used outside Server Actions)
만약 라우트 핸들러(API 엔드포인트)에서 updateTag를 쓰면 어떻게 될까요? 바로 에러가 뿜어져 나옵니다.
import { updateTag } from 'next/cache'
export async function POST() {
// 이 코드는 에러를 발생시킵니다!
updateTag('posts')
// 에러 메시지: updateTag can only be called from within a Server Action (updateTag는 서버 액션 내부에서만 호출할 수 있습니다)
// Route Handlers에서는 대신 revalidateTag를 사용하세요.
revalidateTag('posts', 'max')
}언제 어떤 것을 사용해야 할까? (When to use updateTag)
실무에서 결정 장애가 오지 않도록 확실히 정리해 드리겠습니다!
이럴 때는 updateTag를 사용하세요:
- 현재 코드가 서버 액션(Server Action) 내부일 때
- "내가 쓴 글 바로 읽기"를 위해 즉각적이고 확실한 캐시 무효화가 필요할 때
- 다음 번 데이터 요청 시 무조건 낡은 데이터 대신 업데이트된 최신 데이터를 봐야만 할 때
이럴 때는 대신 revalidateTag를 사용하세요:
- 현재 코드가 Route Handler 등 서버 액션이 아닌 다른 곳일 때
- 뒤에서는 새 데이터를 불러오되, 사용자에게는 우선 캐시된 데이터를 빠르게 보여주는
stale-while-revalidate방식이 필요할 때 - 외부 웹훅(Webhook)이나 캐시 무효화를 위한 전용 API 엔드포인트를 구축할 때
관련 문서 (Related)
더 깊이 공부하고 싶으신 분들은 아래 문서들도 꼭 한번 읽어보시길 권장합니다.
revalidateTag- Route Handlers 등에서 태그 기반으로 캐시를 무효화할 때 사용합니다.revalidatePath- 태그가 아닌 특정 URL 경로(Path)를 기준으로 캐시를 무효화할 때 사용합니다.
전체 문서의 의미론적 개요를 보려면 https://nextjs.org/docs/sitemap.md 를 확인하세요.
사용 가능한 모든 문서의 색인을 보려면 https://nextjs.org/docs/llms.txt 를 확인하세요.
자, 여기까지 Next.js의 updateTag에 대해 원본 문서를 바탕으로 상세하게 번역하고 추가적인 팁까지 다뤄보았습니다. 캐시 제어는 처음에 개념 잡기가 까다롭지만, 한 번 이해하고 나면 웹 애플리케이션의 성능과 사용자 경험을 폭발적으로 끌어올릴 수 있는 강력한 무기가 될 거예요.
혹시 이 내용 중에서 서버 액션(Server Action)의 동작 방식이나, 예제 코드에 나온 redirect 처리 부분에 대해 추가로 궁금한 점이 있으신가요? 언제든 편하게 물어보세요!
