Next.js 서버 액션과 클라이언트 Fetch를 혼합할 때 발생하는 캐싱 문제 해결법

Next.js 13 이후 App Router가 도입되고, 14에서 Server Actions가 공식 기능으로 강화되면서 서버 중심 아키텍처를 적용하는 프로젝트가 증가하고 있다. 이 과정에서 많은 개발자들이 공통적으로 겪는 어려움이 있다. 바로 Server Actions와 클라이언트 Fetch 요청이 함께 쓰일 때 발생하는 캐싱 문제다.

Next.js는 기본적으로 "서버 중심 렌더링과 캐싱"을 강력하게 밀어붙이는 프레임워크다. 그러나 이 구조는 Server Actions와 fetch API가 뒤섞인 실제 환경에서는 예기치 못한 버그를 만든다. 이 글에서는 이러한 문제들이 왜 발생하는지, 그리고 이를 어떻게 해결할 수 있는지 실제 코드 기반으로 정리해본다.

---

1. 왜 Server Actions와 Fetch를 혼용하면 문제가 생기는가

Next.js의 fetch는 기본적으로 서버에서 실행될 때 다음과 같은 특징을 가진다.

• 동일한 fetch 요청은 동일한 입력에 대해 자동 캐싱된다.
• Response는 빌드 시점, 재요청 시점, 혹은 경로의 캐싱 정책에 따라 공유된다.
• Server Component에서는 fetch가 서버 캐시를 적극적으로 활용한다.

반면 Server Actions는 다음 특성을 가진다.

• 실행될 때 자동으로 revalidate를 트리거하지 않는다.
• Action 호출 후 UI가 자동으로 갱신되지 않는다.
• Server Component가 아니라 Client Component에서 호출될 수 있다.

즉, 이 둘이 조합되는 상황에서 다음과 같은 전형적인 문제가 쉽게 발생한다.

---

2. 전형적인 문제 사례

문제 1. Server Action으로 데이터를 수정했지만 UI는 그대로인 경우

예시 코드:

// server action
export async function updateName(id: string, name: string) {
  await prisma.user.update({ where: { id }, data: { name } });
}

그리고 서버 컴포넌트에서 데이터 패칭:

const user = await fetch("https://api.example.com/user/1").then(res => res.json());

문제는 updateName 실행 후에도 fetch가 이전 캐시된 값을 그대로 반환한다는 점이다.

즉, DB 변경은 완료되었지만 Next.js는 이를 모르는 상태다.

---

문제 2. 클라이언트 Fetch는 최신 데이터를 가져오지만 서버 컴포넌트는 캐싱된 데이터를 유지

클라이언트에서 다음처럼 재요청하면:

const res = await fetch("/api/user/1", { cache: "no-store" });

항상 최신 데이터를 가져온다.

그러나 페이지는 서버 컴포넌트에서 패칭된 캐시된 데이터를 그대로 보여준다.

---

문제 3. fetch가 자동 캐싱된다는 점을 인지하지 못한 상태에서 발생하는 교차 버그

App Router의 기본 fetch 정책:

• 서버에서 실행: default = cache: “force-cache”
• 클라이언트 Fetch: default = cache: “no-store”

즉, 같은 URL을 호출해도 서버/클라이언트 결과가 달라진다.

---

3. 해결 전략 정리

이 문제는 여러 방식으로 해결할 수 있다. 대표적인 전략 4가지는 다음과 같다.

1) fetch에서 캐싱을 명시적으로 제어한다

가장 간단한 방법이다.

서버 컴포넌트에서 기본 fetch를 사용하는 대신 다음처럼 명시하는 것이다.

await fetch(url, { cache: "no-store" })

또는

await fetch(url, { next: { revalidate: 0 } })

이 두 방식은 완전히 캐싱을 무효화한다.

다만, 모든 요청에서 no-store를 쓰는 것은 성능 면에서 큰 손실이 있다.

---

2) Server Actions에서 revalidatePath 또는 revalidateTag 사용

Server Actions를 통해 데이터가 변경되면 UI가 최신 상태를 가져올 수 있도록 강제로 revalidation을 트리거해야 한다.

가장 권장되는 방법은 다음 두 가지이다.

revalidatePath

import { revalidatePath } from "next/cache";

export async function updateName(id: string, name: string) {
  await prisma.user.update({ where: { id }, data: { name } });
  revalidatePath("/users"); // 특정 경로 다시 렌더링
}

revalidateTag

fetch에 태그를 붙이고 revalidateTag를 호출하는 방식이다.

// 서버 컴포넌트
await fetch(url, { next: { tags: ["users"] } });

// 서버 액션
revalidateTag("users");

이 방식은 가장 안정적인 UI 갱신 방식을 제공한다.

---

3) Route Handler(API)와 Server Actions의 역할을 분리

많은 개발자들이 흔히 겪는 문제는 다음 구조에서 발생한다.

• 데이터 조회: 서버 컴포넌트 fetch
• 데이터 수정: 서버 액션
• 재조회: 클라이언트 fetch

이 구조는 캐시 일관성을 보장하지 못한다.

이때 해결 전략은 매우 간단하다.

데이터 읽기와 쓰기를 “Route Handler(API)” 중심으로 통합하는 것이다.

예:

// GET /api/users
export async function GET() {
  const users = await prisma.user.findMany();
  return Response.json(users);
}

그리고 fetch 할 때:

fetch("/api/users", { cache: "no-store" });

Server Actions는 오직 mutate 역할만 하도록 구성한다.

이렇게 분리하면 캐싱 충돌이 크게 줄어든다.

---

4) 서버 액션 내부에서 가능한 fetch 호출을 피한다

많은 개발자가 서버 액션 내부에서 fetch를 재활용하려고 한다.

await fetch("/api/user/1", { cache: "force-cache" });

그러나 Server Actions는 기본적으로 Next.js의 fetch 캐시와 충돌할 수 있으며, 불필요한 중복 작업을 만든다.

서버 액션에서는 데이터 소스(DB, Prisma 등)에 직접 접근하는 편이 안전하다.

---

4. 실전 적용 예제

아래는 Next.js 14 기준으로 가장 안정적이고 권장되는 구조다.

1) 서버 컴포넌트 데이터 패칭

// app/users/page.tsx
export default async function UsersPage() {
  const users = await fetch("https://example.com/api/users", {next: { tags: ["users"] },
  }).then((res) => res.json());

  return <UsersList users={users} />;
}

2) 서버 액션에서 데이터 수정 + revalidateTag 호출

"use server";

import { prisma } from "@/lib/prisma";
import { revalidateTag } from "next/cache";

export async function updateUserName(id: string, name: string) {
  await prisma.user.update({ where: { id }, data: { name } });
  revalidateTag("users");
}

3) 클라이언트에서 Server Actions 호출

"use client";
import { updateUserName } from "./actions";

export default function EditForm() {
  async function onSubmit() {await updateUserName("1", "New Name");
  }

  return <button onClick={onSubmit}>Update</button>;
}

이 구조는 캐싱 충돌 없이 항상 최신 UI를 유지할 수 있다.

---

5. 결론

Next.js의 Server Actions와 fetch는 매우 강력한 기능이지만, 서로 다른 캐싱 전략을 개별적으로 가지고 있기 때문에 혼용될 때 문제가 발생하기 쉽다.

핵심 요약은 다음과 같다.

1. Next.js 서버 fetch는 기본적으로 캐싱된다.
2. Server Actions는 자동으로 revalidate를 하지 않는다.
3. Server Action 실행 후 UI를 갱신하려면 revalidatePath 또는 revalidateTag를 사용해야 한다.
4. fetch 요청은 no-store 또는 revalidate 옵션을 명시적으로 설정해야 한다.
5. Route Handler와 Server Actions의 책임을 분리하면 캐싱 충돌을 줄일 수 있다.

이 원리를 이해하면 App Router 기반의 Next.js 애플리케이션에서 안정적이고 예측 가능한 데이터 흐름을 설계할 수 있다.