한 줄 고치려고 빌드를 돌릴 필요는 없습니다

일반적인 Vercel 배포는 코드, 의존성, 환경 변수를 함께 다시 컴파일합니다. 작은 문구 수정도 전체 릴리스가 됩니다. 반면 렌더러는 이미 배포된 상태이고, DB-only 발행은 글 데이터만 바꾼 뒤 캐시 무효화 신호만 보냅니다.

여기서 핵심 명제는 “데이터 레인만 움직이는 발행 루프”입니다. ISR과 revalidatePath, revalidateTag의 역할을 정확히 이해한 뒤, 읽기 경로까지 같이 확인해야 “200은 성공, 화면은 갱신”이 성립합니다.

세 레인

[로컬 원천]      [DB 런타임]        [공개 화면]
local JSON ──▶ Turso row ──▶ Next.js page
     ▲              │                │
     │              ▼                ▼
[ Git 보관 ]   [ revalidate API ]  [ live smoke ]

왼쪽은 사람이 쓰는 원본, 가운데는 시스템이 쓰는 저장소, 오른쪽은 독자가 보는 캐시된 페이지입니다. 코드 레인은 그대로 두고 가운데만 움직이는 것이 핵심입니다.

revalidate가 실제로 하는 일과 안 하는 일

여기서 대부분의 오해가 생깁니다. 정확히 정리하면 이렇습니다.

revalidate는 빌드가 아닙니다. 200 응답은 “무효화 표시가 전달됨”이지, “즉시 재생성이 끝남”이 아닙니다. stale-while-revalidate 구간에서는 첫 smoke 요청이 옛 화면을 받을 수도 있고, 그 자체가 실패로 단정할 수 없습니다.

revalidatePath 인자 규칙

• 리터럴 경로(/vibe-coding/my-post)를 넘길 때는 type을 생략합니다. 그 한 페이지만 무효화됩니다.
• 패턴(/vibe-coding/[slug])을 넘길 때는 type: 'page'가 필수입니다. 그리고 매칭되는 전부가 무효화됩니다.
• /page나 /layout을 문자열 끝에 붙이지 않습니다. 그것은 type으로 표현합니다.

💡 Tip: 성공 기준은 curl 응답이 아니라 라이브 URL에서 새 제목이 보이는지입니다. 상세와 목록 양쪽을 각각 확인하고, 필요하면 2~5회 재시도 smoke로 stale 구간을 넘깁니다.

데이터 변경과 코드 변경 구분

원본의 표는 그대로 유효합니다. 작업 시작 전에 사람에게도 AI에게도 먼저 보여주는 용도입니다.

전제 하나를 명시해 둡니다. 렌더러가 이미 안정적일 때만 이 루프가 성립합니다. 표가 깨지거나 코드블록이 안 나오면 JSON이 아니라 컴포넌트를 고쳐야 합니다.

⚠️ 주의: AI에게 “이 글 고쳐줘”만 던지면 renderer까지 PR이 나올 수 있습니다. 프롬프트에 “content JSON만 다룬다”를 고정하세요.

revalidate 엔드포인트

App Router 기준 예시입니다. app/api/revalidate/route.ts에 둡니다.

import { revalidatePath, revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';
import { timingSafeEqual } from 'node:crypto';

export const runtime = 'nodejs';

function safeEqual(given: string, secret: string) {
  const a = Buffer.from(given, 'utf8');
  const b = Buffer.from(secret, 'utf8');
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

export async function POST(req: NextRequest) {
  const secret = process.env.REVALIDATE_SECRET;
  const given = req.headers.get('x-revalidate-auth');
  if (!secret || !given || !safeEqual(given, secret)) {
    return NextResponse.json({ ok: false, error: 'unauthorized' }, { status: 401 });
  }

  let body: { slug?: string; category?: string };
  try {
    body = await req.json();
  } catch {
    return NextResponse.json({ ok: false, error: 'invalid json' }, { status: 400 });
  }

  const { slug, category } = body;
  if (!slug || !category) {
    return NextResponse.json({ ok: false, error: 'missing slug or category' }, { status: 400 });
  }

  if (!/^[a-z0-9-]+$/.test(slug) || !/^[a-z0-9-]+$/.test(category)) {
    return NextResponse.json({ ok: false, error: 'invalid slug or category' }, { status: 400 });
  }

  const paths = [`/${category}/${slug}`, `/${category}`, '/'];

  try {
    for (const p of paths) revalidatePath(p);
    revalidateTag(`posts:${category}`);
    revalidateTag('posts:home');
    revalidatePath('/sitemap.xml');
  } catch (err) {
    return NextResponse.json(
      { ok: false, error: 'revalidate failed', detail: String(err) },
      { status: 500 },
    );
  }

  return NextResponse.json({
    ok: true,
    marked: paths,
    note: 'invalidation applies on next visit; verify with a live fetch',
  });
}

REVALIDATE_SECRET은 NEXT_PUBLIC_ 접두사를 붙이지 마세요. 붙는 순간 빌드 결과물에 노출됩니다. 또한 성공 판단은 200이 아니라 라이브 smoke 결과로 합니다.

그래서 검증은 이렇게 한다

읽을 값이 두 가지입니다. 본문에 “새 제목” 마커가 있는지, 그리고 캐시 헤더가 stale 구간을 통과했는지입니다. revalidateTag는 기본적으로 stale-while-revalidate 구간을 남기기 때문에, 첫 방문이 옛 화면을 주는 것은 정상 동작일 수 있습니다.

#!/usr/bin/env bash
set -euo pipefail

URL="$1"
MARKER="$2"

for i in 1 2 3 4 5; do
  BODY="$(curl -sS --compressed -H 'Cache-Control: no-cache' "$URL")"
  if echo "$BODY" | grep -qF "$MARKER"; then
    echo "OK  $URL  (attempt $i)"
    exit 0
  fi
  echo "..  $URL  not yet (attempt $i)"
  sleep 2
done

echo "FAIL $URL  marker not found: $MARKER" >&2
exit 1

검증은 반드시 상세와 목록 양쪽을 봅니다.

./scripts/smoke.sh "https://example.com/vibe-coding/my-post" "새 제목 문자열"
./scripts/smoke.sh "https://example.com/vibe-coding"          "새 제목 문자열"

조용히 실패하는 세 가지

모든 단계가 성공처럼 보여도 화면만 옛날인 경우는 보통 세 가지입니다. 가장 어려운 유형입니다.

임베디드 리플리카가 옛 데이터를 캐시로 굳힌다

Turso embedded replicas를 쓰면 쓰기는 원격으로 가고, 읽기는 로컬 복제본에서 옵니다. 복제본은 syncInterval 주기로 따라잡습니다. 발행 루프는 upsert 후 곧바로 revalidate를 보내고, 다음 방문 때 렌더러가 로컬 복제본을 읽습니다.

결과적으로 캐시는 “신선한 것처럼” 굳고, 다음 동기화가 끝나도 저절로 갱신되지 않습니다. 다음 발행 때까지 옛 글이 걸려 있는 현상이 나옵니다.

해결은 발행 스크립트가 revalidate 전에 “재생성 요청이 읽는 경로에서 새 값이 보이는지”를 확인하는 것입니다. 쓰기 경로와 읽기 경로가 다르면 항상 생기는 현상입니다.

인스턴스가 둘이면 한 대만 갱신된다

기본 Next.js 캐시는 인스턴스별로 로컬에 붙습니다. revalidateTag는 호출을 받은 인스턴스에서만 무효화됩니다. 로드밸런서 뒤에서 요청이 분산되면 새 글과 옛 글이 번갈아 보일 수 있습니다.

자체 호스팅에서 인스턴스가 여러 개라면 shared cache를 쓰거나, 커스텀 캐시 핸들러로 refreshTags 같은 동기화를 붙여야 합니다.

CDN은 revalidate를 모른다

ISR은 s-maxage와 stale-while-revalidate를 응답합니다. 앞단 CDN이 이 지시자를 존중해 HTML을 캐시하고 있다면, Next.js 내부 캐시 무효화만으로는 HTML이 바로 바뀌지 않습니다.

CDN이 앞단에 있으면 purge가 발행 루프의 필수 단계입니다. revalidate 직후 해당 URL만 골라 purge하고 smoke를 다시 돌리세요.

발행 루프

원본의 6단계에 위 내용을 반영하면 8단계가 됩니다.

완료 기준은 curl 성공이 아니라 라이브 URL에서 “새 제목이 보이는지”입니다.

되돌리기는 Git revert가 아니다

DB만 바꾸면 Git 히스토리에 흔적이 없습니다. 응급 조치는 상태 토글로 합니다.

UPDATE posts SET status = 'draft', published_at = NULL WHERE slug = 'problem-slug';

이후 revalidate를 호출하면 공개 화면에서 사라집니다. 글 row는 DB에 남아 조사 후 재공개할 수 있습니다. 되돌린 뒤에는 목록과 sitemap도 함께 smoke로 다시 확인하세요.

⚠️ 주의: 되돌릴 때는 상세만 내리지 말고 목록과 sitemap도 함께 무효화하세요. 그렇지 않으면 죽은 링크가 남습니다.

AI에게 맡길 때는 경계를 문장으로 쓴다

나쁜 예는 “AI 뉴스 1개 올려줘”처럼 범위와 검증 경계를 빼먹는 지시입니다. 이 루프에서는 AI를 작성자가 아니라 운영자 절차를 따라 실행하는 도구로 둡니다.

1. content/vibe/<slug>.json에만 파일을 작성한다.
2. validation과 금지어 grep을 통과할 때까지 고친다.
3. publish 스크립트는 승인 후에만 실행한다.
4. 상세 URL과 목록 URL 양쪽에 live smoke를 돌린다.
5. 실패 시 보류 보고하고 다음 수정으로 넘어가지 않는다.

금지: app/, components/, lib/ 이하 파일 수정. DB 직접 접속 금지. 불확실하면 진행 중지와 근거 보고.

체크리스트

작업 전에는 데이터 변경인지 코드 변경인지 구분하고, 로컬 JSON 원본과 되돌리기 방법이 있는지 확인합니다.

검증 중에는 스키마 검증, 금지어 grep, slug/id 일치, 본문 실행 가치가 있어야 합니다.

공개 후에는 revalidate 경로(상세, 목록, 홈, sitemap), live smoke(상세와 목록), 콘솔 오류를 같이 확인합니다.

출처와 링크

• Next.js revalidatePath: 경로별 무효화
• Next.js revalidateTag: 태그 일괄 무효화
• Next.js updateTag: read-your-own-writes
• Next.js Draft Mode: draft 모드 렌더
• Turso embedded replicas: 읽기 지연과 동기화
• Cloudflare Cache Purge: CDN 캐시 잔존 시

조사 기준: 2026년 7월. Next.js 14+ App Router와 Turso CLI 기준입니다. Pages Router나 다른 DB면 API와 스크립트 경로를 바꿔야 합니다.