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

// 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>;
}

// 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;

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

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

// 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>
    </>
  );
}