NNext.js 中文网 GitHub

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

针对某个请求绕过 Next.js 缓存,使编辑者能够预览来自 headless CMS 的未发布内容。

Draft Mode 让编辑者能够查看草稿或进行中的内容在你的网站上将如何渲染,而无需等待重新验证。当编辑者处于 Draft Mode 时,缓存或预渲染的内容会被绕过,直接从上游源获取。其他访客仍然会看到页面的缓存或预渲染版本。

如果你的 CMS 从同一 URL 提供草稿和已发布内容,你的数据获取代码无需更改。否则,请参阅当你的 CMS 使用单独的草稿端点时。

Draft Mode 的作用#

当某个请求启用了 Draft Mode 时:

  • fetch() 调用会跳过 Next.js fetch 缓存,直接访问网络。
  • 'use cache' 内的组件和函数会在每次请求时重新执行,其结果不会保存到缓存。
  • unstable_cache 的读取和写入也会以同样的方式被绕过。
  • 该页面会被排除在 ISR 响应缓存之外,并以 Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate 提供。

无论页面是静态生成的、从缓存提供的,还是通过 ISR 重新验证的,此效果都适用。

本指南涵盖的内容#

本指南假设:

  • 你的 headless CMS 支持可配置的预览 URL(大多数都支持)。
  • 当编辑者点击"Preview"时,CMS 会在新标签页中打开类似 /api/draft?secret=XXX&slug=/posts/foo 的 URL。secret 是共享令牌;slug 是要预览的路径。
  • 你的 Next.js 应用会验证 secret、启用 Draft Mode,并重定向到该 slug。

基于这一约定,本指南的其余部分将逐步介绍:

  1. 创建一个通过设置 cookie 来启用 Draft Mode 的 Route Handler。
  2. 使用来自 CMS 的共享 secret 和 slug 保护该 handler。
  3. 渲染读取最新草稿的页面。
  4. 显示带有退出表单的预览横幅。

然后,根据你的设置:

小知识: GET 旨在成为安全的只读方法。影响未来请求的操作(例如通过 cookie 启用 Draft Mode)应使用 POST。入口 handler 使用 GET,因为我们假设是 CMS 预览集成:CMS 会在新的浏览器标签页中打开 URL,这是一个 GET 请求。第 4 步中的退出流程使用 POST(通过 Server Action 或 POST Route Handler)。

第 1 步:创建 Route Handler#

创建一个设置 Draft Mode cookie 的 Route Handler。它可以取任意名称,例如 app/api/draft/route.ts。

app/api/draft/route.ts
import { draftMode } from 'next/headers'

export async function GET(request: Request) {
  const draft = await draftMode()
  draft.enable()
  return new Response('Draft mode is enabled')
}
app/api/draft/route.js
import { draftMode } from 'next/headers'

export async function GET(request) {
  const draft = await draftMode()
  draft.enable()
  return new Response('Draft mode is enabled')
}

draft.enable() 会设置一个名为 __prerender_bypass 的 cookie。随后携带此 cookie 的请求会跳过上面列出的每一层缓存。

你可以通过访问 /api/draft 并查看浏览器的开发者工具来手动测试。注意 Set-Cookie 响应头。

按照目前的写法,该 handler 是公开的:任何访问 /api/draft 的人都会为自己启用 Draft Mode。第 2 步会用共享 secret 关闭这一点,以便只有你的 CMS 可以调用它。

第 2 步:从你的 headless CMS 访问 Route Handler#

这些步骤假设你使用的 headless CMS 支持设置自定义草稿 URL。如果不支持,你仍然可以使用此方法保护草稿 URL,但需要手动构造并访问草稿 URL。具体步骤会因你使用的 headless CMS 而异。

要从 headless CMS 安全地访问 Route Handler:

  1. 使用你选择的令牌生成器创建一个secret 令牌字符串。此 secret 只有你的 Next.js 应用和 headless CMS 知道。
  2. 如果你的 headless CMS 支持设置自定义草稿 URL,请指定一个草稿 URL(这里假设你的 Route Handler 位于 app/api/draft/route.ts)。例如:
Terminal
https://<your-site>/api/draft?secret=<token>&slug=<path>
  • <your-site> 应为你的部署域名。
  • <token> 应替换为你生成的 secret 令牌。
  • <path> 应为你要查看的页面的路径。如果要查看 /posts/one,则应使用 &slug=/posts/one。

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

  1. 在 Route Handler 中,检查 secret 是否匹配以及 slug 参数是否存在(如果不存在,请求应失败),调用 draft.enable() 设置 cookie,然后将浏览器重定向到 slug 指定的路径:
app/api/draft/route.ts
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const secret = searchParams.get('secret')
  const slug = searchParams.get('slug')

  // 此 secret 只应由此 Route Handler 和 CMS 知晓
  if (secret !== 'MY_SECRET_TOKEN' || !slug) {
    return new Response('Invalid token', { status: 401 })
  }

  // 在启用 Draft Mode 之前,验证 slug 在 CMS 中存在
  const post = await getPostBySlug(slug)
  if (!post) {
    return new Response('Invalid slug', { status: 401 })
  }

  const draft = await draftMode()
  draft.enable()

  // 重定向到从获取到的 post 中取得的路径,而不是 searchParams 中的路径,
  // 以避免开放重定向漏洞
  redirect(post.slug)
}
app/api/draft/route.js
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

export async function GET(request) {
  const { searchParams } = new URL(request.url)
  const secret = searchParams.get('secret')
  const slug = searchParams.get('slug')

  if (secret !== 'MY_SECRET_TOKEN' || !slug) {
    return new Response('Invalid token', { status: 401 })
  }

  const post = await getPostBySlug(slug)
  if (!post) {
    return new Response('Invalid slug', { status: 401 })
  }

  const draft = await draftMode()
  draft.enable()

  redirect(post.slug)
}

如果成功,浏览器会被重定向到目标路径,并设置 Draft Mode cookie。

第 3 步:预览草稿内容#

由于 Draft Mode 会自动绕过缓存,你的页面无需知道 Draft Mode 是否开启即可接收新鲜内容。像平常一样获取即可:

app/posts/[slug]/page.tsx
async function getPost(slug: string) {
  const res = await fetch(`https://cms.example.com/posts/${slug}`)
  return res.json()
}

export default async function Page({ params }: PageProps<'/posts/[slug]'>) {
  const { slug } = await params
  const post = await getPost(slug)

  return (
    <main>
      <h1>{post.title}</h1>
      <article>{post.content}</article>
    </main>
  )
}
app/posts/[slug]/page.js
async function getPost(slug) {
  const res = await fetch(`https://cms.example.com/posts/${slug}`)
  return res.json()
}

export default async function Page({ params }) {
  const { slug } = await params
  const post = await getPost(slug)

  return (
    <main>
      <h1>{post.title}</h1>
      <article>{post.content}</article>
    </main>
  )
}

当存在 Draft Mode cookie 时,上面的 fetch 会跳过 Next.js fetch 缓存,直接访问你的 CMS 获取当前草稿。当不存在时,同一请求可以照常从缓存提供。

如果你的 CMS 使用不同的 URL 提供草稿,而不是从同一端点提供,请参阅当你的 CMS 使用单独的草稿端点时。

第 4 步:显示预览指示器#

isEnabled 最有用的场景是作为给编辑者的信号:一个确认他们正在查看草稿内容的横幅,以及退出的方法。从根布局渲染一个指示器,使其出现在每个预览页面上。

app/preview-banner.tsx
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

async function exitPreview() {
  'use server'
  const draft = await draftMode()
  draft.disable()
  redirect('/')
}

export async function PreviewBanner() {
  const { isEnabled } = await draftMode()
  if (!isEnabled) return null

  return (
    <aside role="status">
      Preview mode is on.{' '}
      <form action={exitPreview}>
        <button type="submit">Exit preview</button>
      </form>
    </aside>
  )
}
app/preview-banner.js
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

async function exitPreview() {
  'use server'
  const draft = await draftMode()
  draft.disable()
  redirect('/')
}

export async function PreviewBanner() {
  const { isEnabled } = await draftMode()
  if (!isEnabled) return null

  return (
    <aside role="status">
      Preview mode is on.{' '}
      <form action={exitPreview}>
        <button type="submit">Exit preview</button>
      </form>
    </aside>
  )
}

退出 Draft Mode 也可以使用 GET Route Handler,但 POST 在语义上更正确,例如通过 Server Action 提交的表单或提交到 POST Route Handler。

如果你确实使用 GET Route Handler,请从 <form method="GET"> 触发它,而不要使用 <Link>。Next.js 默认会预取 <Link> 组件,这会在编辑者点击之前就清除 cookie。表单不会被预取,无论使用何种方法。

结合 Cache Components 使用 Draft Mode#

你可以在 'use cache' 作用域内读取 isEnabled,以便从缓存组件呈现预览指示器。缓存绕过仍然适用,因此组件会在每次草稿请求时使用新鲜数据重新执行。

app/posts/[slug]/page.tsx
import { draftMode } from 'next/headers'

async function Post({ slug }: { slug: string }) {
  'use cache'

  const post = await fetch(`https://cms.example.com/posts/${slug}`).then((r) =>
    r.json()
  )
  const { isEnabled } = await draftMode()

  return (
    <article>
      {isEnabled && <p role="status">Draft preview</p>}
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}
app/posts/[slug]/page.js
import { draftMode } from 'next/headers'

async function Post({ slug }) {
  'use cache'

  const post = await fetch(`https://cms.example.com/posts/${slug}`).then((r) =>
    r.json()
  )
  const { isEnabled } = await draftMode()

  return (
    <article>
      {isEnabled && <p role="status">Draft preview</p>}
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}

小知识: draftMode().enable() 和 draftMode().disable() 不能在缓存指令作用域内调用;请改为从 Route Handler 或 Server Action 切换 Draft Mode。

当你的 CMS 使用单独的草稿端点时#

如果你的 CMS 在不同的 URL 提供草稿内容,或需要不同的凭据,请根据 isEnabled 对 fetch 进行分支:

app/posts/[slug]/page.tsx
import { draftMode } from 'next/headers'

async function getPost(slug: string) {
  const { isEnabled } = await draftMode()
  const baseUrl = isEnabled
    ? 'https://cms.example.com/preview'
    : 'https://cms.example.com/published'

  const res = await fetch(`${baseUrl}/posts/${slug}`)
  return res.json()
}
app/posts/[slug]/page.js
import { draftMode } from 'next/headers'

async function getPost(slug) {
  const { isEnabled } = await draftMode()
  const baseUrl = isEnabled
    ? 'https://cms.example.com/preview'
    : 'https://cms.example.com/published'

  const res = await fetch(`${baseUrl}/posts/${slug}`)
  return res.json()
}

缓存绕过仍然适用于两个分支;该分支只决定从何处读取。

Next.js 中文网