Vercel ISR 完整指南：增量静态再生策略、缓存失效与性能优化

// middleware.ts - 错误地添加 vary 会导致缓存膨胀
export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  // ❌ 不要基于 Cookie 或 User-Agent 设置 Vary
  response.headers.set('Vary', 'Cookie');
  return response;
}

// 通过 revalidateTag 实现全局级联失效
await revalidateTag('posts'); // 影响所有带 'posts' tag 的页面和数据缓存

curl -sI https://yoursite.com/blog/hello | grep x-vercel-cache
# HIT  - 缓存命中
# MISS - 未命中（首次或已失效）
# STALE- 返回旧版本，正在后台重新生成
# BYPASS- 显式绕过缓存

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation';

interface PageProps {
  params: { slug: string };
}

// 页面级别的 ISR 配置
// 3600 = 1 小时后后台重新验证
export const revalidate = 3600;

export default async function BlogPostPage({ params }: PageProps) {
  const post = await fetch(`https://api.example.com/posts/${params.slug}`, {
    next: { revalidate: 3600 }, // fetch 级别也可以指定
  }).then(r => r.json());

  if (!post) return notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      <time>{new Date(post.date).toLocaleDateString()}</time>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  // 构建时预生成这些路径
  const posts = await fetch('https://api.example.com/posts').then(r => r.json());

  return posts.map((post: any) => ({
    slug: post.slug,
  }));
}

export const revalidate = 3600;

// 访问构建时未生成的路径 → 执行 ISR（首次访问生成 + 缓存）
export const dynamicParams = true; // 默认开启

// 1. 数据缓存 1 小时（最多每小时更新一次）
const data = await fetch('https://api.example.com/data', {
  next: { revalidate: 3600 },
});

// 2. 数据每次请求都更新（类似 SSR）
const data = await fetch('https://api.example.com/data', {
  cache: 'no-store',
});

// 3. 数据永久缓存（类似 SSG）
const data = await fetch('https://api.example.com/data', {
  cache: 'force-cache',
});

// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret');
  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 });
  }

  const { path, tag } = await request.json();

  try {
    if (path) {
      revalidatePath(path);
      return NextResponse.json({ revalidated: true, path });
    }

    if (tag) {
      revalidateTag(tag);
      return NextResponse.json({ revalidated: true, tag });
    }

    return NextResponse.json({ error: 'Missing path or tag' }, { status: 400 });
  } catch (err) {
    return NextResponse.json({ error: 'Revalidation failed' }, { status: 500 });
  }
}

# 重新验证特定页面
curl -X POST https://yoursite.com/api/revalidate \
  -H "Content-Type: application/json" \
  -H "x-revalidate-secret: your-secret" \
  -d '{"path": "/blog/hello-world"}'

# 重新验证所有带 "posts" 标签的数据
curl -X POST https://yoursite.com/api/revalidate \
  -H "Content-Type: application/json" \
  -H "x-revalidate-secret: your-secret" \
  -d '{"tag": "posts"}'

// 获取文章列表（带 cacheTag）
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { tags: ['posts'] },
  });
  return res.json();
}

// app/blog/page.tsx
export default async function BlogListPage() {
  const posts = await getPosts();
  return (
    <ul>
      {posts.map((post: any) => (
        <li key={post.slug}><a href={`/blog/${post.slug}`}>{post.title}</a></li>
      ))}
    </ul>
  );
}

// 用 revalidateTag('posts') 可以同时刷新列表页和所有详情页
// 因为详情页可能也使用了相同的 fetch tags

// next.config.js
module.exports = {
  experimental: {
    ppr: true,
  },
};

// app/page.tsx
import { Suspense } from 'react';
import StaticContent from './static-content';
import DynamicContent from './dynamic-content';

export default function Page() {
  return (
    <div>
      {/* 这部分构建时静态生成 */}
      <StaticContent />

      {/* 这部分每次请求实时获取 */}
      <Suspense fallback={<div>Loading...</div>}>
        <DynamicContent />
      </Suspense>
    </div>
  );
}

// app/dynamic-content.tsx
import { unstable_noStore } from 'next/cache';

export default async function DynamicContent() {
  unstable_noStore(); // 禁用缓存，每请求执行

  const data = await fetch('https://api.example.com/live-data');
  return <div>{data}</div>;
}

// ❌ N+1：列表页中逐个查询每篇文章的作者
export default async function BlogListPage() {
  const posts = await prisma.post.findMany();
  // 每个 post 触发一次新的查询
  for (const post of posts) {
    post.author = await prisma.user.findUnique({ where: { id: post.authorId } });
  }
  // ...
}

// ✅ 一次性 JOIN
export default async function BlogListPage() {
  const posts = await prisma.post.findMany({
    include: { author: true },
  });
  // ...
}

// lib/dataloader.ts
import DataLoader from 'dataloader';
import { prisma } from './prisma';

export const userLoader = new DataLoader(async (authorIds: readonly string[]) => {
  const users = await prisma.user.findMany({
    where: { id: { in: [...authorIds] } },
  });
  const userMap = new Map(users.map(u => [u.id, u]));
  return authorIds.map(id => userMap.get(id));
});

// app/blog/[slug]/page.tsx
import { userLoader } from '@/lib/dataloader';

export const revalidate = 3600;

export default async function BlogPostPage({ params }: { params: { slug: string } }) {
  const post = await prisma.post.findUnique({ where: { slug: params.slug } });
  if (!post) return notFound();

  const author = await userLoader.load(post.authorId);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>作者：{author?.name}</p>
    </article>
  );
}

// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.NODE_ENV === 'development' ? ['query', 'info', 'warn', 'error'] : ['error'],
});

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// 带超时的 ISR fetch + fallback 缓存
async function fetchProduct(slug: string) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 8000);

  try {
    const res = await fetch(`https://api.example.com/products/${slug}`, {
      signal: controller.signal,
      next: { revalidate: 3600 },
    });
    clearTimeout(timeout);
    if (!res.ok) throw new Error('API error');
    return res.json();
  } catch (err) {
    // 降级：读取上一次的缓存值或返回占位数据
    return getStaleCacheOrFallback(slug);
  }
}

// lib/isr-lock.ts
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();

export async function acquireRebuildLock(key: string, ttlSeconds: number): Promise<boolean> {
  const lockKey = `isr:lock:${key}`;
  const acquired = await redis.set(lockKey, '1', { nx: true, ex: ttlSeconds });
  return acquired === 'OK';
}

// 在 API Route 内的 on-demand revalidation 前检查锁
export async function POST(request: NextRequest) {
  const { path } = await request.json();
  const hasLock = await acquireRebuildLock(path, 30);
  if (!hasLock) {
    return NextResponse.json({ revalidated: false, reason: 'already-rebuilding' });
  }
  revalidatePath(path);
  return NextResponse.json({ revalidated: true, path });
}

export default async function Page() {
  const posts = await fetchPosts();

  if (!posts?.length) {
    // 仍然返回页面，但标记为 1 小时后再次尝试
    return <div>暂无内容</div>;
  }
  // ...
}

// lib/cache-config.ts
const isProduction = process.env.NODE_ENV === 'production';

export const CACHE_CONFIG = {
  homePage: isProduction ? 300 : 0,        // 开发环境不缓存
  blogList: isProduction ? 3600 : 0,
  blogPost: isProduction ? 86400 : 0,
  productList: isProduction ? 600 : 0,
  productDetail: isProduction ? 3600 : 0,
  staticPage: isProduction ? false : 0,    // false = SSG（永不更新）
};

// app/blog/page.tsx
import { CACHE_CONFIG } from '@/lib/cache-config';

export const revalidate = CACHE_CONFIG.blogList;

// lib/cache-config.ts - 生产级预算控制配置
const isProduction = process.env.NODE_ENV === 'production';

// 根据实际 Vercel 账单动态调整
const FUNCTION_BUDGET_GB_HOURS = 5; // 每月预算上限

export const CACHE_CONFIG = {
  // 高流量页面：最大化缓存收益
  highTraffic: isProduction ? 7200 : 0,   // 2 小时
  // 中流量页面：平衡
  mediumTraffic: isProduction ? 3600 : 0, // 1 小时
  // 长尾页面：降低重新生成频率
  lowTraffic: isProduction ? 86400 : 0,   // 1 天
  // 列表页：用 on-demand 触发
  listPage: isProduction ? 3600 : 0,
};

// app/[locale]/blog/[slug]/page.tsx
interface PageProps {
  params: { locale: string; slug: string };
}

export const revalidate = 3600;

// 构建时预生成所有语言 × 所有文章的组合
export async function generateStaticParams() {
  const locales = ['en', 'zh', 'ja'];
  const posts = await fetch('https://api.example.com/posts').then(r => r.json());

  const params: { locale: string; slug: string }[] = [];
  for (const locale of locales) {
    for (const post of posts) {
      params.push({ locale, slug: post.slug });
    }
  }
  return params;
}

export default async function BlogPostPage({ params }: PageProps) {
  const { locale, slug } = params;
  const post = await fetch(`https://api.example.com/posts/${slug}?lang=${locale}`)
    .then(r => r.json());

  if (!post) return notFound();

  return (
    <article lang={locale}>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const locales = ['en', 'zh', 'ja'];
const defaultLocale = 'en';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // 检查路径是否已包含语言前缀
  const pathnameHasLocale = locales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );

  if (pathnameHasLocale) return NextResponse.next();

  // 从 Cookie 或 Accept-Language 头检测语言
  const locale = request.cookies.get('NEXT_LOCALE')?.value
    || request.headers.get('accept-language')?.split(',')[0].split('-')[0]
    || defaultLocale;

  const finalLocale = locales.includes(locale) ? locale : defaultLocale;

  // 重写到带语言前缀的路径
  request.nextUrl.pathname = `/${finalLocale}${pathname}`;
  return NextResponse.rewrite(request.nextUrl);
}

export const config = {
  matcher: ['/((?!api|_next|favicon.ico).*)'],
};

// middleware.ts - 根据 subdomain 路由
export function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') || '';
  const subdomain = hostname.replace('.example.com', '');

  const url = request.nextUrl.clone();
  url.pathname = `/${subdomain}${url.pathname}`;

  return NextResponse.rewrite(url);
}

// app/[tenant]/dashboard/page.tsx
export const revalidate = 300;

export default async function TenantDashboard({ params }: { params: { tenant: string } }) {
  const tenant = await fetch(`https://api.example.com/tenants/${params.tenant}`).then(r => r.json());
  if (!tenant) return notFound();

  return <div>Welcome to {tenant.name}</div>;
}

// app/[tenant]/dashboard/page.tsx（与上述相同）
// 缓存键天然包含 tenant 路径，无需额外配置

// ❌ 危险：基于 Cookie vary 缓存
// 不支持在 Vercel ISR 中使用
response.headers.set('Vary', 'Cookie');

// ✅ 安全：租户信息在 URL 路径中
// /tenant-a/profile 与 /tenant-b/profile 是独立缓存

// app/api/revalidate/route.ts
export async function POST(request: NextRequest) {
  const { path, tenant, tag } = await request.json();

  if (tenant) {
    // 重新验证特定租户的页面
    revalidatePath(`/${tenant}${path}`);
  }

  if (tag) {
    // revalidateTag 会跨租户失效，配合租户前缀标签
    revalidateTag(`${tenant}:${tag}`);
  }

  return NextResponse.json({ revalidated: true });
}

// middleware.ts
// ❌ 重写到同一路径但不带参数，可能导致缓存失效
return NextResponse.rewrite(new URL('/blog/hello-world', request.url));

// ✅ 保留原始路径参数
request.nextUrl.searchParams.set('middleware-processed', 'true');
return NextResponse.next({ request });

// ✅ 数据缺失时返回 404 而非 500
export default async function BlogPostPage({ params }: PageProps) {
  try {
    const post = await fetchPost(params.slug);
    if (!post) return notFound(); // 404，不触 ISR 500
    return <article>{/* ... */}</article>;
  } catch (err) {
    // 降级：返回最后一次成功的缓存（已在 ISR 缓存中）
    // 注意：此 catch 只在首次生成时有效，缓存过期后的 catch
    // 如果再次抛异常仍会导致 500
    return notFound();
  }
}

export async function generateStaticParams() {
  const posts = await fetchPosts();
  return posts.map(post => ({
    slug: encodeURIComponent(post.slug),
  }));
}

export default async function Page({ params }: { params: { slug: string } }) {
  const slug = decodeURIComponent(params.slug); // 解码
  const post = await fetchPost(slug);
  // ...
}

// next.config.js
module.exports = {
  async redirects() {
    return [
      // ❌ 这会阻止 /old-blog/hello 的 ISR
      {
        source: '/old-blog/:slug',
        destination: '/blog/:slug',
        permanent: true,
      },
    ];
  },
};

// middleware.ts
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/old-blog/')) {
    const slug = request.nextUrl.pathname.replace('/old-blog/', '');
    return NextResponse.rewrite(new URL(`/blog/${slug}`, request.url));
  }
  return NextResponse.next();
}

// lib/isr-telemetry.ts
interface ISRTelemetry {
  path: string;
  status: 'HIT' | 'MISS' | 'STALE' | 'REVALIDATED';
  timestamp: number;
  duration?: number;
}

export async function trackISR(event: ISRTelemetry) {
  // 发送到自建日志服务或 Vercel Analytics
  if (process.env.ANALYTICS_API_KEY) {
    await fetch('https://analytics.example.com/isr-events', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event),
    }).catch(() => {}); // 非阻塞
  }
}

// app/api/revalidate/route.ts
import { trackISR } from '@/lib/isr-telemetry';

export async function POST(request: NextRequest) {
  const { path } = await request.json();
  const start = Date.now();

  try {
    revalidatePath(path);

    await trackISR({
      path,
      status: 'REVALIDATED',
      timestamp: Date.now(),
      duration: Date.now() - start,
    });

    return NextResponse.json({ revalidated: true });
  } catch (err) {
    await trackISR({
      path,
      status: 'MISS',
      timestamp: Date.now(),
    });
    return NextResponse.json({ error: 'Failed' }, { status: 500 });
  }
}

// middleware.ts - 注入缓存状态到 page props
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();

  // 在 HTML 中注入缓存状态标记（仅开发/调试）
  response.headers.set('x-isr-debug', 'enabled');
  return response;
}

// scripts/monitor-cache.ts
const TARGET_URLS = [
  'https://yoursite.com/',
  'https://yoursite.com/blog/hello',
  'https://yoursite.com/products/123',
];

async function checkCacheHitRatio() {
  const results = await Promise.all(
    TARGET_URLS.map(async (url) => {
      const res = await fetch(url, { cache: 'no-store' }); // 跳过浏览器缓存
      const cacheStatus = res.headers.get('x-vercel-cache');
      return { url, cacheStatus };
    })
  );

  const hits = results.filter(r => r.cacheStatus === 'HIT').length;
  const ratio = hits / results.length;

  console.log(`Cache Hit Ratio: ${(ratio * 100).toFixed(1)}%`);

  if (ratio < 0.9) {
    // 发送告警（Slack, PagerDuty, etc）
    await sendAlert(`ISR cache hit ratio dropped to ${(ratio * 100).toFixed(1)}%`);
  }
}

// app/api/monitor-isr/route.ts
export async function GET(request: NextRequest) {
  // 仅允许 Cron 触发
  const auth = request.headers.get('authorization');
  if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const urls = ['/', '/blog', '/products'];
  let hitCount = 0;

  for (const path of urls) {
    const res = await fetch(`${process.env.SITE_URL}${path}`, {
      cache: 'no-store',
    });
    const cacheStatus = res.headers.get('x-vercel-cache');
    if (cacheStatus === 'HIT') hitCount++;
  }

  const ratio = hitCount / urls.length;

  if (ratio < 0.9) {
    // 调用 Slack Webhook
    await fetch(process.env.SLACK_WEBHOOK_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        text: `⚠️ ISR Cache Alert: Hit ratio dropped to ${(ratio * 100).toFixed(0)}%\nChecked URLs: ${urls.join(', ')}`,
      }),
    });
  }

  return NextResponse.json({ ratio, checked: urls.length });
}

{
  "crons": [
    {
      "path": "/api/monitor-isr",
      "schedule": "0 */6 * * *"
    }
  ]
}

// lib/isr-retry.ts
import { revalidatePath } from 'next/cache';

const MAX_RETRIES = 3;
const RETRY_DELAY_MS = 5000;

export async function revalidateWithRetry(path: string, attempt = 1): Promise<boolean> {
  try {
    revalidatePath(path);
    return true;
  } catch (err) {
    if (attempt >= MAX_RETRIES) {
      console.error(`ISR revalidation failed after ${MAX_RETRIES} attempts: ${path}`);
      // 记录到持久化日志或告警
      return false;
    }
    await new Promise(resolve => setTimeout(resolve, RETRY_DELAY_MS));
    return revalidateWithRetry(path, attempt + 1);
  }
}

// app/api/webhook/cms/route.ts
export async function POST(request: NextRequest) {
  const payload = await request.json();

  if (payload.event === 'post.published') {
    const success = await revalidateWithRetry(`/blog/${payload.slug}`);
    if (!success) {
      //  fallback：队列任务稍后重试，或通知运维
      await enqueueRetry(`/blog/${payload.slug}`);
    }
  }

  return NextResponse.json({ processed: true });
}

// app/blog/page.tsx
export default async function BlogListPage() {
  const posts = await getPosts();

  return (
    <>
      {/* 开发环境显示缓存提示 */}
      {process.env.NODE_ENV === 'development' && (
        <script>{`console.log('[ISR] Blog list rendered at', new Date().toISOString())`}</script>
      )}
      <ul>{/* ... */}</ul>
    </>
  );
}

// lib/cache-layer.ts
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();

export async function getCachedPost(slug: string, freshness: number = 3600) {
  const cacheKey = `post:${slug}`;
  const cached = await redis.get(cacheKey);

  if (cached) {
    return JSON.parse(cached as string);
  }

  const post = await prisma.post.findUnique({ where: { slug } });
  await redis.setex(cacheKey, freshness, JSON.stringify(post));
  return post;
}

// 生产级 ISR fallback 模式
export default async function Page() {
  try {
    const data = await fetchDataWithTimeout(8000);
    if (!data) {
      // 空值 fallback：返回静态提示
      return <div>暂无数据</div>;
    }
    return <Content data={data} />;
  } catch (err) {
    // 异常 fallback：返回静态降级页面
    return <ErrorFallback />;
  }
}

# 自动化验证脚本
#!/bin/bash
URL="https://yoursite.com/blog/hello"
echo "First request:"
curl -sI "$URL" | grep x-vercel-cache
sleep 5
echo "Second request (should be HIT):"
curl -sI "$URL" | grep x-vercel-cache