NNext.js 中文网 GitHub

如何在 Next.js 中使用预览模式(Preview Mode)预览内容

legacy

Next.js 为静态生成的页面提供了预览模式。你可以在这里了解它的工作原理。

注意:此功能已被草稿模式(Draft Mode)取代。

<details> <summary>示例</summary>

</details>

在 Pages 文档和数据获取文档中,我们讨论了如何使用 getStaticProps 和 getStaticPaths 在构建时预渲染页面(静态生成(Static Generation))。

当你的页面从 headless CMS 获取数据时,静态生成非常有用。然而,当你在 headless CMS 上撰写草稿并希望在页面上立即预览该草稿时,它并不理想。你希望 Next.js 在请求时而非构建时渲染这些页面,并获取草稿内容而非已发布的内容。你希望 Next.js 仅在这种特定情况下绕过静态生成。

Next.js 提供了一个名为预览模式(Preview Mode)的功能来解决这个问题。以下是使用它的说明。

第 1 步:创建并访问预览 API 路由#

如果你不熟悉 Next.js API Routes,请先查看 API Routes 文档。

首先,创建一个预览 API 路由。它可以有任何名称,例如 pages/api/preview.js(如果使用 TypeScript,则为 .ts)。

在这个 API 路由中,你需要在响应对象上调用 setPreviewData。setPreviewData 的参数应该是一个对象,getStaticProps 可以使用它(稍后会详细介绍)。目前,我们使用 {}。

js
export default function handler(req, res) {
  // ...
  res.setPreviewData({})
  // ...
}

res.setPreviewData 会在浏览器上设置一些 cookie,从而开启预览模式。任何包含这些 cookie 的、发往 Next.js 的请求都会被视为预览模式,静态生成页面的行为也会随之改变(稍后会详细介绍)。

你可以通过创建如下所示的 API 路由并从浏览器手动访问它来手动测试:

pages/api/preview.js
// 用于从浏览器手动测试的简单示例。
export default function handler(req, res) {
  res.setPreviewData({})
  res.end('Preview mode enabled')
}

如果你打开浏览器的开发者工具并访问 /api/preview,你会注意到此请求中设置了 __prerender_bypass 和 __next_preview_data cookie。

从 headless CMS 安全地访问它#

在实践中,你希望从 headless CMS 安全地 调用这个 API 路由。具体步骤因你所使用的 headless CMS 而异,但以下是一些可以采取的常见步骤。

这些步骤假设你使用的 headless CMS 支持设置自定义预览 URL。如果不支持,你仍然可以使用此方法来保护预览 URL 的安全,但你需要手动构造并访问预览 URL。

首先,你应该使用你选择的令牌生成器创建一个密钥令牌字符串。这个密钥只有你的 Next.js 应用和 headless CMS 知道。它可以防止无权访问你 CMS 的人访问预览 URL。

其次,如果你的 headless CMS 支持设置自定义预览 URL,请将以下内容指定为预览 URL。这里假设你的预览 API 路由位于 pages/api/preview.js。

Terminal
https://<your-site>/api/preview?secret=<token>&slug=<path>
  • <your-site> 应该是你的部署域名。
  • <token> 应替换为你生成的密钥令牌。
  • <path> 应该是你想要预览的页面的路径。如果你想预览 /posts/foo,则应使用 &slug=/posts/foo。

你的 headless CMS 可能允许你在预览 URL 中包含一个变量,以便根据 CMS 的数据动态设置 <path>,例如:&slug=/posts/{entry.fields.slug}

最后,在预览 API 路由中:

  • 检查密钥是否匹配,以及 slug 参数是否存在(如果不存在,请求应失败)。

-

  • 调用 res.setPreviewData。
  • 然后将浏览器重定向到 slug 指定的路径。(以下示例使用了 307 重定向)。
js
export default async (req, res) => {
  // 检查密钥和后续参数
  // 此密钥应仅由此 API 路由和 CMS 知道
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  // 请求 headless CMS 以检查提供的 `slug` 是否存在
  // getPostBySlug 将实现对 headless CMS 的必要获取逻辑
  const post = await getPostBySlug(req.query.slug)

  // 如果 slug 不存在,则阻止启用预览模式
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }

  // 通过设置 cookie 来启用预览模式
  res.setPreviewData({})

  // 重定向到所获取文章中的路径
  // 我们不重定向到 req.query.slug,因为那可能导致开放重定向漏洞
  res.redirect(post.slug)
}

如果成功,浏览器将被重定向到你想预览的路径,并设置预览模式的 cookie。

第 2 步:更新 getStaticProps#

下一步是更新 getStaticProps 以支持预览模式。

如果你请求一个带有 getStaticProps 的页面,且已设置预览模式 cookie(通过 res.setPreviewData),那么 getStaticProps 将在请求时(而非构建时)被调用。

此外,它将接收一个 context 对象被调用,其中:

  • context.preview 将为 true。
  • context.previewData 将与传给 setPreviewData 的参数相同。
js
export async function getStaticProps(context) {
  // 如果你在设置了预览模式 cookie 的情况下请求此页面:
  //
  // - context.preview 将为 true
  // - context.previewData 将与以下内容相同
  //   传给 `setPreviewData` 的参数。
}

我们在预览 API 路由中使用了 res.setPreviewData({}),因此 context.previewData 将为 {}。如有必要,你可以用它来将会话信息从预览 API 路由传递到 getStaticProps。

如果你还使用了 getStaticPaths,那么 context.params 也将可用。

获取预览数据#

你可以更新 getStaticProps,根据 context.preview 和/或 context.previewData 获取不同的数据。

例如,你的 headless CMS 可能为草稿文章提供不同的 API 端点。如果是这样,你可以使用 context.preview 来修改 API 端点 URL,如下所示:

js
export async function getStaticProps(context) {
  // 如果 context.preview 为 true,则在 API 端点后追加 "/preview"
  // 以请求草稿数据而非已发布的数据。具体会因
  // 你所使用的 headless CMS 而异。
  const res = await fetch(`https://.../${context.preview ? 'preview' : ''}`)
  // ...
}

就是这样!如果你从 headless CMS 或手动访问预览 API 路由(带有 secret 和 slug),你现在应该能够看到预览内容。而且,如果你在不发布的情况下更新草稿,你应该能够预览该草稿。

将此设置为 headless CMS 上的预览 URL,或手动访问它,你应该能够看到预览内容。

Terminal
https://<your-site>/api/preview?secret=<token>&slug=<path>

更多细节#

小知识:在渲染期间,next/router 会暴露一个 isPreview 标志,有关更多信息,请参阅 router 对象文档。

指定预览模式的持续时间#

setPreviewData 接受一个可选的第二个参数,该参数应该是一个选项对象。它接受以下键:

  • maxAge:指定预览会话持续的秒数。
  • path:指定应用 cookie 的路径。默认为 /,即为所有路径启用预览模式。
js
setPreviewData(data, {
  maxAge: 60 * 60, // 预览模式 cookie 在 1 小时后过期
  path: '/about', // 预览模式 cookie 适用于包含 /about 的路径
})

默认情况下,预览模式的 cookie 不会设置过期日期,因此预览会话会在浏览器关闭时结束。

要手动清除预览模式的 cookie,请创建一个调用 clearPreviewData() 的 API 路由:

pages/api/clear-preview-mode-cookies.js
export default function handler(req, res) {
  res.clearPreviewData({})
}

然后,向 /api/clear-preview-mode-cookies 发送请求以调用该 API 路由。如果使用 next/link 调用此路由,你必须传入 prefetch={false},以防止在链接预取期间调用 clearPreviewData。

如果在 setPreviewData 调用中指定了路径,则必须将相同的路径传给 clearPreviewData:

pages/api/clear-preview-mode-cookies.js
export default function handler(req, res) {
  const { path } = req.query

  res.clearPreviewData({ path })
}

previewData 大小限制#

你可以向 setPreviewData 传入一个对象,使其在 getStaticProps 中可用。但是,由于数据将存储在 cookie 中,因此存在大小限制。目前,预览数据限制为 2KB。

与 getServerSideProps 配合使用#

预览模式也适用于 getServerSideProps。包含 preview 和 previewData 的 context 对象同样可用。

小知识:使用预览模式时不应设置 Cache-Control 标头,因为它无法被绕过。相反,我们建议使用 ISR。

与 API Routes 配合使用#

API Routes 可以在请求对象下访问 preview 和 previewData。例如:

js
export default function myApiRoute(req, res) {
  const isPreview = req.preview
  const previewData = req.previewData
  // ...
}

每次 next build 都是唯一的#

当 next build 完成时,绕过 cookie 的值和用于加密 previewData 的私钥都会发生变化。 这确保绕过 cookie 无法被猜测。

小知识:要通过 HTTP 在本地测试预览模式,你的浏览器需要允许第三方 cookie 和本地存储访问。

Next.js 中文网