Next.js 教程系列（九）增量静态再生 (ISR)：动态更新的静态内容

前言

大家好，我是鲫小鱼。是一名不写前端代码的前端工程师，热衷于分享非前端的知识，带领切图仔逃离切图圈子，欢迎关注我，微信公众号：《鲫小鱼不正经》。欢迎点赞、收藏、关注，一键三连！！

第九章增量静态再生 (ISR)：动态更新的静态内容

一、理论讲解

1. ISR 核心理念与底层原理

增量静态再生（Incremental Static Regeneration，简称 ISR）是 Next.js 独有的混合渲染模式，允许开发者在不重新构建整个站点的情况下，按需、定时地更新部分静态页面。它结合了 SSG 的高性能和 SSR 的实时性，极大提升了大规模内容站点的可维护性和性能。

定时再生 ：通过 revalidate 参数，Next.js 会在后台定期重新生成页面。
按需再生：支持 API 触发（on-demand revalidation），如管理员操作、Webhook 通知等。
CDN 协同：与 CDN 缓存结合，保证全球访问速度。
无感知更新：用户访问时总能拿到最新或最近一次生成的内容。
极致性能：首次请求生成静态页面，后续请求直接命中 CDN，只有到期或手动触发时才会后台再生。

ISR 与 CDN 协同流程

用户访问页面，CDN 检查缓存是否过期。
若缓存有效，直接返回静态页面。
若缓存过期，CDN 允许请求到达 Next.js 服务器，后台异步再生页面，用户仍拿到旧内容。
再生完成后，CDN 缓存自动更新，后续用户访问即为新内容。

revalidate 机制流程图（文字描述）

用户访问页面 → CDN 检查缓存 → 缓存有效：直接返回 → 缓存过期：Next.js 触发再生 → 新页面生成 → CDN 缓存更新

2. revalidate 参数与 on-demand revalidation

revalidate 是 getStaticProps 返回对象中的一个字段，单位为秒，表示页面静态内容的最小刷新间隔。
on-demand revalidation 允许通过 API 路由手动触发某个页面或路径的再生，适合内容管理后台、Webhook 场景。
支持按路径、按 tag、全站等多种粒度的再生。

按 tag/on-demand revalidate

Next.js 13+ 支持 revalidateTag，可按 tag 精细化刷新相关页面。

3. 与 SSR/SSG 区别

SSG：构建时一次性生成所有静态页面，后续内容变更需重新构建。
SSR：每次请求都实时生成页面，性能受限于服务端。
ISR：首次请求生成静态页面，后续定时或手动再生，兼顾性能与实时性。

4. 适用场景与企业级案例

大型内容站点（如博客、新闻、商品详情）
需要频繁更新但不要求秒级实时的页面
管理后台、内容平台、SEO 友好型站点
典型案例：电商商品页、新闻门户、内容聚合平台

5. 常见误区与优化建议

ISR 不是实时渲染，存在短暂的"旧内容"窗口
revalidate 过短会导致频繁构建，影响性能
on-demand revalidation 需做好权限校验，防止滥用
CDN 配置不当会导致缓存失效不及时
建议结合监控，及时发现再生失败等异常

二、代码示例

1. 商品详情页用 ISR 定时更新

ts 复制代码

// pages/products/[id].tsx
export async function getStaticPaths() {
  const products = await fetchProducts();
  return {
    paths: products.map(p => ({ params: { id: p.id } })),
    fallback: 'blocking',
  };
}

export async function getStaticProps({ params }) {
  const product = await fetchProductById(params.id);
  if (!product) return { notFound: true };
  return {
    props: { product },
    revalidate: 60, // 每 60 秒自动再生
  };
}

export default function ProductPage({ product }) {
  return (
    <div className="product-detail">
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <span>价格：{product.price}</span>
    </div>
  );
}

2. 多种 on-demand revalidate 场景

按路径手动刷新

ts 复制代码

// pages/api/revalidate.ts
export default async function handler(req, res) {
  const { secret, path } = req.query;
  if (secret !== process.env.REVALIDATE_SECRET) {
    return res.status(401).json({ message: '无权限' });
  }
  try {
    await res.revalidate(path);
    return res.json({ revalidated: true });
  } catch (err) {
    // 错误监控
    reportError(err);
    return res.status(500).json({ message: 'revalidate 失败' });
  }
}

按 tag 手动刷新（Next.js 13+）

ts 复制代码

// app/api/revalidate-tag/route.ts
import { revalidateTag } from 'next/cache';
export async function POST(req) {
  const { tag, secret } = await req.json();
  if (secret !== process.env.REVALIDATE_SECRET) return new Response('无权限', { status: 401 });
  try {
    revalidateTag(tag);
    return Response.json({ revalidated: true });
  } catch (err) {
    reportError(err);
    return Response.json({ message: 'revalidate 失败' }, { status: 500 });
  }
}

3. 前端触发手动刷新（管理员操作）

tsx 复制代码

// components/AdminRevalidateButton.tsx
import { useState } from 'react';
export default function AdminRevalidateButton() {
  const [loading, setLoading] = useState(false);
  const handleRevalidate = async () => {
    setLoading(true);
    const res = await fetch('/api/revalidate?path=/', {
      headers: { 'x-admin-token': localStorage.getItem('adminToken') },
    });
    setLoading(false);
    alert((await res.json()).revalidated ? '刷新成功' : '刷新失败');
  };
  return <button onClick={handleRevalidate} disabled={loading}>{loading ? '刷新中...' : '手动刷新首页'}</button>;
}

4. 移动端骨架屏动画

css 复制代码

.skeleton {
  background: linear-gradient(90deg, #eee 25%, #f5f5f5 50%, #eee 75%);
  background-size: 200% 100%;
  animation: skeleton 1.2s infinite linear;
  height: 80px;
  border-radius: 8px;
  margin-bottom: 12px;
}
@keyframes skeleton {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

5. 错误监控与埋点

js 复制代码

// pages/_app.tsx
import { useEffect } from 'react';
useEffect(() => {
  window.addEventListener('error', (e) => {
    // 上报 ISR 相关错误
    reportError(e);
  });
}, []);

三、实战项目：博客系统热门文章列表（ISR 自动+手动更新）

1. 项目需求

博客首页展示热门文章列表，内容每隔 5 分钟自动更新
管理员可在后台一键刷新热门列表（on-demand revalidation）
移动端友好，SEO 友好，性能高
支持骨架屏动画、错误兜底、性能监控、结构化数据

2. 技术选型

Next.js + TypeScript
getStaticProps + revalidate
API 路由手动 revalidate
CDN 缓存
Sentry/自研埋点监控

3. 目录结构

text 复制代码

/blog-hot-demo
  |-- pages/
      |-- index.tsx
      |-- api/
          |-- revalidate.ts
  |-- components/
      |-- HotList.tsx
      |-- AdminRevalidateButton.tsx
      |-- Skeleton.tsx
  |-- styles/
      |-- globals.css

4. 首页热门文章列表（自动+手动再生）

ts 复制代码

// pages/index.tsx
import HotList from '../components/HotList';
import AdminRevalidateButton from '../components/AdminRevalidateButton';
import Skeleton from '../components/Skeleton';
import Head from 'next/head';
export async function getStaticProps() {
  const hotPosts = await fetchHotPosts();
  return {
    props: { hotPosts },
    revalidate: 300, // 5 分钟自动再生
  };
}
export default function Home({ hotPosts }) {
  return (
    <>
      <Head>
        <title>热门文章 - 博客系统</title>
        <meta name="description" content="最新最热的博客文章，定时自动更新，SEO 友好" />
        <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify({
          "@context": "https://schema.org",
          "@type": "ItemList",
          "itemListElement": hotPosts.map((p, i) => ({
            "@type": "ListItem",
            "position": i + 1,
            "url": `/posts/${p.id}`
          }))
        }) }} />
      </Head>
      <AdminRevalidateButton />
      {hotPosts.length === 0 ? <Skeleton /> : <HotList posts={hotPosts} />}
    </>
  );
}

ts 复制代码

// components/HotList.tsx
export default function HotList({ posts }) {
  return (
    <ul className="hot-list">
      {posts.map(post => (
        <li key={post.id}>
          <a href={`/posts/${post.id}`}>{post.title}</a>
        </li>
      ))}
    </ul>
  );
}

tsx 复制代码

// components/AdminRevalidateButton.tsx
import { useState } from 'react';
export default function AdminRevalidateButton() {
  const [loading, setLoading] = useState(false);
  const handleRevalidate = async () => {
    setLoading(true);
    const res = await fetch('/api/revalidate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'x-admin-token': localStorage.getItem('adminToken') },
      body: JSON.stringify({ secret: 'xxx' })
    });
    setLoading(false);
    alert((await res.json()).revalidated ? '刷新成功' : '刷新失败');
  };
  return <button onClick={handleRevalidate} disabled={loading}>{loading ? '刷新中...' : '手动刷新首页'}</button>;
}

ts 复制代码

// components/Skeleton.tsx
export default function Skeleton() {
  return <div className="skeleton">加载中...</div>;
}

ts 复制代码

// pages/api/revalidate.ts
export default async function handler(req, res) {
  if (req.method !== 'POST') return res.status(405).end();
  const { secret } = req.body;
  if (secret !== process.env.REVALIDATE_SECRET) return res.status(401).json({ message: '无权限' });
  try {
    await res.revalidate('/');
    return res.json({ revalidated: true });
  } catch (err) {
    reportError(err);
    return res.status(500).json({ message: 'revalidate 失败' });
  }
}

5. 移动端适配与性能优化

css 复制代码

.hot-list { padding: 0; }
.hot-list li { margin-bottom: 12px; }
@media (max-width: 600px) {
  .hot-list { font-size: 16px; }
  .skeleton { height: 60px; }
}

四、最佳实践

合理设置 revalidate 间隔：根据内容更新频率和业务需求设置，避免过短导致频繁构建。

ts 复制代码

revalidate: 300 // 5 分钟

on-demand revalidation 权限校验：API 路由需校验 secret，防止被恶意刷接口。

ts 复制代码

if (secret !== process.env.REVALIDATE_SECRET) return res.status(401).json({ message: '无权限' });

缓存失效与 CDN 配合：合理设置响应头，利用 CDN 缓存提升全球访问速度。

ts 复制代码

res.setHeader('Cache-Control', 'public, s-maxage=300, stale-while-revalidate');

错误处理与监控报警：revalidate 失败需有日志和报警，便于排查。

ts 复制代码

try { await res.revalidate('/'); } catch (err) { reportError(err); }

团队协作与权限管理：约定好哪些页面用 ISR，哪些用 SSR/SSG，文档化 revalidate 策略，管理员操作需鉴权。

ts 复制代码

if (!isAdmin(req)) return res.status(403).json({ message: '无权限' });

极端场景降级：如再生失败、接口超时，前端兜底提示，保证用户体验。

tsx 复制代码

if (error) return <div>热门文章加载失败，请稍后重试</div>;

五、常见问题与解决方案

Q: ISR 页面内容有延迟，怎么解决？
- A: 适当缩短 revalidate 间隔，或结合 on-demand revalidation。
Q: 手动 revalidate 失败？
- A: 检查 secret、API 路由权限、路径拼写、管理员权限。
Q: CDN 缓存未及时失效？
- A: 检查 CDN 配置，确保支持 stale-while-revalidate。
Q: SEO 有问题？
- A: ISR 页面本质为静态页面，SEO 友好，注意 meta 标签和结构化数据。
Q: 频繁 revalidate 导致性能下降？
- A: 合理设置 revalidate 间隔，避免高频触发。
Q: 再生失败如何监控？
- A: 集成 Sentry/自研埋点，自动报警。
Q: 如何做多页面/多 tag 刷新？
- A: 使用 revalidatePath/revalidateTag，或循环调用 revalidate。
Q: 用户看到旧内容怎么办？
- A: 可在前端提示"内容已更新，点击刷新"，或自动轮询。

最后感谢阅读！欢迎关注我，微信公众号：《鲫小鱼不正经》。欢迎点赞、收藏、关注，一键三连！！！

Next.js 教程系列（九）增量静态再生 (ISR)：动态更新的静态内容

前言

第九章 增量静态再生 (ISR)：动态更新的静态内容

一、理论讲解

1. ISR 核心理念与底层原理

ISR 与 CDN 协同流程

revalidate 机制流程图（文字描述）

2. revalidate 参数与 on-demand revalidation

按 tag/on-demand revalidate

3. 与 SSR/SSG 区别

4. 适用场景与企业级案例

5. 常见误区与优化建议

二、代码示例

1. 商品详情页用 ISR 定时更新

2. 多种 on-demand revalidate 场景

按路径手动刷新

按 tag 手动刷新（Next.js 13+）

3. 前端触发手动刷新（管理员操作）

4. 移动端骨架屏动画

5. 错误监控与埋点

三、实战项目：博客系统热门文章列表（ISR 自动+手动更新）

1. 项目需求

2. 技术选型

3. 目录结构

4. 首页热门文章列表（自动+手动再生）

5. 移动端适配与性能优化

四、最佳实践

五、常见问题与解决方案

第九章增量静态再生 (ISR)：动态更新的静态内容