Next.js 12 On-Demand Revalidation 教程

概述

On-Demand Revalidation 是 Next.js 自 11.1 版本开始支持的一项功能，它允许开发者通过 API 路由手动触发页面的重新验证和重新生成。这在需要手动控制内容更新，而不想等待增量静态生成（ISR，Incremental Static Regeneration）的默认时间间隔时，特别有用。

在 Next.js 12 中，这项功能得到了完全支持。下面是实现 On-Demand Revalidation 的完整教程。

1、配置环境变量

首先，需要配置一个用于安全验证的密钥。这个密钥将用于确保只有授权的请求才能触发页面的重新验证。

在项目根目录下创建 .env.local 文件，并添加以下内容：

REVALIDATION_SECRET=your_secret_token

可以将 your_secret_token 替换为任意一个复杂的字符串。

2、创建 API 路由

接下来，创建一个 API 路由，负责处理触发页面重新验证的请求。

在 pages/api/revalidate.ts 文件中，添加以下代码：

import { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { secret, path } = req.query;

  // 验证密钥是否匹配
  if (secret !== process.env.REVALIDATION_SECRET) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  try {
    // 重新验证指定的路径
    await res.revalidate(path as string);
    return res.json({ revalidated: true });
  } catch (err) {
    // 捕获并返回错误
    console.error('Revalidation error:', err);
    return res.status(500).json({ message: 'Error revalidating' });
  }
}

此代码创建了一个 API 路由 /api/revalidate，它接收两个查询参数：

secret: 用于验证请求的密钥。
path: 需要重新验证的页面路径。

3、配置页面的增量静态生成

需要在静态生成的页面中使用 getStaticProps 并设置 revalidate 属性来启用增量静态生成。

例如，在 pages/blog/[…slug].tsx 中：

import { GetStaticProps } from 'next';

interface BlogPostProps {
  data: {
    title: string;
    content: string;
  };
}

export const getStaticProps: GetStaticProps<BlogPostProps> = async ({ params }) => {
  const slug = params?.slug as string[];
  const data = await fetchYourData(slug.join('/'));

  return {
    props: {
      data,
    },
    revalidate: 60, // 设置页面60秒后重新生成
  };
};

const BlogPost: React.FC<BlogPostProps> = ({ data }) => {
  return (
    <div>
      <h1>{data.title}</h1>
      <p>{data.content}</p>
    </div>
  );
};

export default BlogPost;

4、触发重新验证

要手动触发页面重新验证，可以向 /api/revalidate 路由发送 GET 请求。请求的 URL 结构如下：

https://yourdomain.com/api/revalidate?secret=your_secret_token&path=/blog/2024/07/demo-name

在此示例中：
your_secret_token 是在环境变量中配置的密钥。
/blog/2024/07/demo-name 是希望重新生成的页面路径。
可以在前端通过 fetch 发送请求，或从任何后台系统中触发这个请求。

5. 调试与错误处理

如果触发重新验证时遇到问题，确保：

路径与生成的静态页面路径完全一致。
使用的密钥与环境变量中的密钥匹配。
输出的错误日志能帮助定位问题。
可以在 catch 块中输出更详细的日志信息来调试：

try {
  await res.revalidate(path as string);
  return res.json({ revalidated: true });
} catch (err) {
  console.error('Revalidation error:', err); // 输出详细错误信息
  return res.status(500).json({ message: 'Error revalidating', error: err.message });
}

6、总结

通过 On-Demand Revalidation 功能，可以手动控制 Next.js 项目中的内容更新，而无需等待预设的增量静态生成时间。这不仅提升了灵活性，也使得内容更新能够更加即时。只需确保配置正确的安全密钥，并在需要时触发重新验证请求，即可利用这一功能。