NNext.js 中文网 GitHub

如何在 Next.js 中使用 Draft Mode 预览内容

Next.js 提供了 Draft Mode 来在静态页面和动态页面之间切换。你可以了解它如何与 Pages Router 一起工作。

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

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

Next.js 有一个名为 Draft Mode 的功能可以解决这个问题。以下是使用方法。

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

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

首先,创建 API 路由。它可以有任何名称,例如 pages/api/draft.ts

在这个 API 路由中,你需要在响应对象上调用 setDraftMode。

js
export default function handler(req, res) {
  // ...
  res.setDraftMode({ enable: true })
  // ...
}

这将设置一个 cookie 来启用 Draft Mode。后续包含此 cookie 的请求将触发 Draft Mode,从而改变静态生成页面的行为(稍后会详细介绍)。

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

pages/api/draft.ts
// 用于从浏览器手动测试的简单示例。
export default function handler(req, res) {
  res.setDraftMode({ enable: true })
  res.end('Draft mode is enabled')
}

如果你打开浏览器的开发者工具并访问 /api/draft,你会注意到一个名为 __prerender_bypass 的 cookie 的 Set-Cookie 响应头。

从无头 CMS 安全地访问它#

实际上,你希望从无头 CMS 安全地 调用这个 API 路由。具体步骤会因你使用的无头 CMS 而异,但以下是一些可以采取的常见步骤。

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

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

其次,如果你的无头 CMS 支持设置自定义草稿 URL,请将以下内容指定为草稿 URL。这假设你的草稿 API 路由位于 pages/api/draft.ts。

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

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

最后,在草稿 API 路由中:

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

-

  • 调用 res.setDraftMode。
  • 然后将浏览器重定向到 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' })
  }

  // 从无头 CMS 获取内容,检查提供的 `slug` 是否存在
  // getPostBySlug 将实现对无头 CMS 所需的获取逻辑
  const post = await getPostBySlug(req.query.slug)

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

  // 通过设置 cookie 启用 Draft Mode
  res.setDraftMode({ enable: true })

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

如果成功,浏览器将被重定向到你要查看的路径,并携带 Draft Mode cookie。

第 2 步:更新 getStaticProps#

下一步是更新 getStaticProps 以支持 Draft Mode。

如果你请求一个带有 getStaticProps 的页面,且该页面已设置 cookie(通过 res.setDraftMode),那么 getStaticProps 将在请求时(而不是构建时)被调用。

此外,调用时会传入一个 context 对象,其中 context.draftMode 将为 true。

js
export async function getStaticProps(context) {
  if (context.draftMode) {
    // 动态数据
  }
}

我们在草稿 API 路由中使用了 res.setDraftMode,因此 context.draftMode 将为 true。

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

获取草稿数据#

你可以更新 getStaticProps,根据 context.draftMode 获取不同的数据。

例如,你的无头 CMS 可能为草稿文章提供不同的 API 端点。如果是这样,你可以像下面这样修改 API 端点 URL:

js
export async function getStaticProps(context) {
  const url = context.draftMode
    ? 'https://draft.example.com'
    : 'https://production.example.com'
  const res = await fetch(url)
  // ...
}

就是这样!如果你从无头 CMS 或手动访问草稿 API 路由(带上 secret 和 slug),你现在应该能够看到草稿内容。如果你更新草稿而不发布,也应该能够查看该草稿。

将它设置为无头 CMS 上的草稿 URL,或手动访问它,你应该就能看到草稿了。

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

更多细节#

默认情况下,Draft Mode 会话会在浏览器关闭时结束。

要手动清除 Draft Mode cookie,请创建一个调用 setDraftMode({ enable: false }) 的 API 路由:

pages/api/disable-draft.ts
export default function handler(req, res) {
  res.setDraftMode({ enable: false })
}

然后,向 /api/disable-draft 发送请求以调用该 API 路由。如果使用 next/link 调用此路由,你必须传入 prefetch={false},以防止在预取时意外删除 cookie。

与 getServerSideProps 配合使用#

Draft Mode 可与 getServerSideProps 配合使用,并在 context 对象中作为 draftMode 键提供。

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

与 API Routes 配合使用#

API Routes 将能够在请求对象上访问 draftMode。例如:

js
export default function myApiRoute(req, res) {
  if (req.draftMode) {
    // 获取草稿数据
  }
}

每次 next build 唯一#

每次运行 next build 时都会生成一个新的绕过 cookie 值。

这确保无法猜测绕过 cookie。

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

Next.js 中文网