incremental-static-rendering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Incremental Static Generation

增量静态生成（iSSG）

Static Generation (SSG) addresses most of the concerns of SSR and CSR but is suitable for rendering mostly static content. It poses limitations when the content to be rendered is dynamic or changing frequently.

Think of a growing blog with multiple posts. You wouldn't possibly want to rebuild and redeploy the site just because you want to correct a typo in one of the posts. Similarly, one new blog post should also not require a rebuild for all the existing pages. Thus, SSG on its own is not enough for rendering large websites or applications.

静态生成（SSG）解决了SSR和CSR的大部分问题，但仅适用于渲染以静态内容为主的页面。当需要渲染的内容是动态或频繁变化时，它就存在局限性。

想象一个不断更新的多文章博客。你肯定不想仅仅因为修正某篇文章里的一个错别字，就重新构建并重新部署整个网站。同样，新增一篇博客文章也不应该需要重新构建所有现有页面。因此，单纯的SSG并不适用于大型网站或应用的渲染需求。

When to Use

适用场景

Use this when you have mostly static pages that need periodic data updates without full rebuilds
This is helpful for large sites (blogs, e-commerce) where rebuilding every page on each change is impractical

当你拥有以静态页面为主，但需要定期更新数据且无需全量重新构建时使用
对于大型站点（如博客、电商平台），每次内容变更就重新构建所有页面并不现实，此时该方案非常实用

Instructions

实现步骤

Use
```
revalidate
```
in
```
getStaticProps
```
to set a time interval for background page regeneration
Use
```
fallback: true
```
in
```
getStaticPaths
```
to lazily generate pages on first request
Consider on-demand revalidation (
```
revalidatePath
```
,
```
revalidateTag
```
) for immediate updates after content changes
In Next.js 13+ App Router, use
```
generateStaticParams
```
and async components for ISR

在
```
getStaticProps
```
中使用
```
revalidate
```
设置后台页面再生的时间间隔
在
```
getStaticPaths
```
中设置
```
fallback: true
```
，实现首次请求时懒生成页面
考虑使用按需重新验证（
```
revalidatePath
```
、
```
revalidateTag
```
），在内容变更后立即更新页面
在Next.js 13+的App Router中，使用
```
generateStaticParams
```
和异步组件实现ISR

Details

详细说明

The Incremental Static Generation (iSSG) pattern was introduced as an upgrade to SSG, to help solve the dynamic data problem and help static sites scale for large amounts of frequently changing data. iSSG allows you to update existing pages and add new ones by pre-rendering a subset of pages in the background even while fresh requests for pages are coming in.

增量静态生成（iSSG）是SSG的升级方案，旨在解决动态数据问题，帮助静态站点应对大量频繁变化的数据并实现规模化。iSSG允许你在后台预渲染部分页面，即使有新的页面请求进来，也能更新现有页面并添加新页面。

Sample Code

示例代码

iSSG works on two fronts to incrementally introduce updates to an existing static site after it has been built.

Allows addition of new pages
Allows updates to existing pages also known as Incremental Static "Re"generation

iSSG从两个方面实现对已构建完成的静态站点进行增量更新：

支持添加新页面
支持更新现有页面（也称为增量静态“重”生）

Adding New pages

添加新页面

The lazy loading concept is used to include new pages on the website after the build. This means that the new page is generated immediately on the first request. While the generation takes place, a fallback page or a loading indicator can be shown to the user on the front-end.

export async function getStaticPaths() {
  const products = await getProductsFromDatabase();

  const paths = products.map((product) => ({
     params: { id: product.id }
  }));

  // fallback: true means that the missing pages
  // will not 404, and instead can render a fallback.
  return { paths, fallback: true };
}

// params will contain the id for each generated page.
export async function getStaticProps({ params }) {
  return {
    props: {
      product: await getProductFromDatabase(params.id)
    }
  }
}

export default function Product({ product }) {
  const router = useRouter();

  if (router.isFallback) {
    return <div>Loading...</div>;
  }

  // Render product
}

Here, we have used

fallback: true

. Now if the page corresponding to a specific product is unavailable, we show a fallback version of the page, eg., a loading indicator as shown in the Product function above. Meanwhile, Next.js will generate the page in the background. Once it is generated, it will be cached and shown instead of the fallback page. The cached version of the page will now be shown to any subsequent visitors immediately upon request.

这里使用懒加载的理念，在网站构建完成后添加新页面。这意味着新页面会在首次请求时立即生成。在生成过程中，前端可以向用户展示回退页面或加载指示器。

export async function getStaticPaths() {
  const products = await getProductsFromDatabase();

  const paths = products.map((product) => ({
     params: { id: product.id }
  }));

  // fallback: true means that the missing pages
  // will not 404, and instead can render a fallback.
  return { paths, fallback: true };
}

// params will contain the id for each generated page.
export async function getStaticProps({ params }) {
  return {
    props: {
      product: await getProductFromDatabase(params.id)
    }
  }
}

export default function Product({ product }) {
  const router = useRouter();

  if (router.isFallback) {
    return <div>Loading...</div>;
  }

  // Render product
}

在这段代码中，我们使用了

fallback: true

。如果某个产品对应的页面尚未生成，我们会向用户展示页面的回退版本，比如上述Product组件中的加载指示器。与此同时，Next.js会在后台生成该页面。生成完成后，页面会被缓存，后续请求将直接展示缓存后的页面，而非回退版本。

Update Existing pages

更新现有页面

To re-render an existing page, a suitable timeout is defined for the page. This will ensure that the page is revalidated whenever the defined timeout period has elapsed. The user will continue to see the previous version of the page, till the page has finished revalidation. Thus, iSSG uses the stale-while-revalidate strategy where the user receives the cached or stale version while the revalidation takes place. The revalidation takes place completely in the background without the need for a full rebuild.

// This function runs at build time on the build server
export async function getStaticProps() {
  return {
    props: {
      products: await getProductsFromDatabase(),
      revalidate: 60, // This will force the page to revalidate after 60 seconds
    }
  }
}

// The page component receives products prop from getStaticProps at build time
export default function Products({ products }) {
  return (
    <>
      <h1>Products</h1>
      <ul>
        {products.map((product) => (
          <li key={product.id}>{product.name}</li>
        ))}
      </ul>
    </>
  )
}

The code to revalidate the page after 60 seconds is included in the

getStaticProps()

function. When a request comes in the available static page is served first. Every one minute the static page gets refreshed in the background with new data. Once generated, the new version of the static file becomes available and will be served for any new requests in the subsequent minute. This feature is available in Next.js 9.5 and above.

要重新渲染现有页面，需要为页面定义一个合适的超时时间。这将确保每当超时时间到期时，页面会重新验证。在页面完成重新验证之前，用户将继续看到页面的旧版本。因此，iSSG采用了stale-while-revalidate策略，即在重新验证过程中，用户会收到缓存的旧版本页面。重新验证完全在后台进行，无需全量重新构建整个站点。

// This function runs at build time on the build server
export async function getStaticProps() {
  return {
    props: {
      products: await getProductsFromDatabase(),
      revalidate: 60, // This will force the page to revalidate after 60 seconds
    }
  }
}

// The page component receives products prop from getStaticProps at build time
export default function Products({ products }) {
  return (
    <>
      <h1>Products</h1>
      <ul>
        {products.map((product) => (
          <li key={product.id}>{product.name}</li>
        ))}
      </ul>
    </>
  )
}

在

getStaticProps()

函数中加入了60秒后重新验证页面的代码。当请求进来时，会先返回已有的静态页面。每隔一分钟，静态页面会在后台用新数据刷新。生成完成后，新版本的静态文件将可用，并在接下来的一分钟内为新请求提供服务。该功能在Next.js 9.5及以上版本中可用。

Advantages

优势

iSSG provides all the advantages of SSG and then some more:

Dynamic data: Its ability to support dynamic data without a need to rebuild the site.
Speed: iSSG is at least as fast as SSG because data retrieval and rendering still takes place in the background. There is little processing required on the client or the server.
Availability: A fairly recent version of any page will always be available online for users to access. Even if the regeneration fails in the background, the old version remains unaltered.
Consistent: As the regeneration takes place on the server one page at a time, the load on the database and the backend is low and performance is consistent. As a result, there are no spikes in latency.
Ease of Distribution: Just like SSG sites, iSSG sites can also be distributed through a network of CDN's used to serve pre-rendered web pages.

Note (React 18+ / Next.js 13+): On-Demand Revalidation
A new best practice is to use On-Demand Revalidation when possible. Next.js provides APIs (e.g.,
res.revalidate
in API routes, or
revalidatePath
and
revalidateTag
in App Router) to trigger revalidation of specific pages immediately after content changes, rather than waiting for the next timed interval.
For fallback pages, the pattern of using
fallback: true
in
getStaticPaths
remains valid. In Next.js 13 App Router, fallback behavior is handled by the
loading.js
conventions automatically.
Edge caching and ISR: Platforms like Vercel and Cloudflare let you run ISR on the edge. ISR is now a standard practice for large sites—refine it with targeted revalidation and good loading states.

iSSG具备SSG的所有优势，同时还新增了以下特性：

动态数据支持：无需重新构建站点即可支持动态数据。
速度优势：iSSG的速度至少与SSG相当，因为数据获取和渲染仍在后台进行，客户端或服务器几乎不需要处理。
高可用性：任何页面的较新版本始终可供用户访问。即使后台再生失败，旧版本也不会受到影响。
性能稳定：由于页面再生在服务器上逐个进行，数据库和后端的负载较低，性能保持稳定，不会出现延迟峰值。
易于分发：与SSG站点一样，iSSG站点也可以通过CDN网络分发，用于提供预渲染的网页。

注意（React 18+ / Next.js 13+）：按需重新验证
一个新的最佳实践是尽可能使用按需重新验证。Next.js提供了API（例如API路由中的
res.revalidate
，或App Router中的
revalidatePath
和
revalidateTag
），可以在内容变更后立即触发特定页面的重新验证，而无需等待下一个定时间隔。
对于回退页面，在
getStaticPaths
中使用
fallback: true
的模式仍然有效。在Next.js 13的App Router中，回退行为由
loading.js
约定自动处理。
边缘缓存与ISR：像Vercel和Cloudflare这样的平台允许你在边缘运行ISR。如今，ISR已成为大型站点的标准实践——通过针对性的重新验证和良好的加载状态来优化它。

Source

来源

patterns.dev/react/incremental-static-rendering

patterns.dev/react/incremental-static-rendering