如何在 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。
基于这一约定,本指南的其余部分将逐步介绍:
- 创建一个通过设置 cookie 来启用 Draft Mode 的 Route Handler。
- 使用来自 CMS 的共享 secret 和 slug 保护该 handler。
- 渲染读取最新草稿的页面。
- 显示带有退出表单的预览横幅。
然后,根据你的设置:
- 结合 Cache Components 使用 Draft Mode,用于从
'use cache'边界呈现预览状态。 - 当你的 CMS 使用单独的草稿端点时,根据
isEnabled对 fetch URL 进行分支。
小知识:
GET旨在成为安全的只读方法。影响未来请求的操作(例如通过 cookie 启用 Draft Mode)应使用POST。入口 handler 使用GET,因为我们假设是 CMS 预览集成:CMS 会在新的浏览器标签页中打开 URL,这是一个GET请求。第 4 步中的退出流程使用POST(通过 Server Action 或POSTRoute Handler)。
第 1 步:创建 Route Handler#
创建一个设置 Draft Mode cookie 的 Route Handler。它可以取任意名称,例如 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')
}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:
- 使用你选择的令牌生成器创建一个secret 令牌字符串。此 secret 只有你的 Next.js 应用和 headless CMS 知道。
- 如果你的 headless CMS 支持设置自定义草稿 URL,请指定一个草稿 URL(这里假设你的 Route Handler 位于
app/api/draft/route.ts)。例如:
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}
- 在 Route Handler 中,检查 secret 是否匹配以及
slug参数是否存在(如果不存在,请求应失败),调用draft.enable()设置 cookie,然后将浏览器重定向到slug指定的路径:
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)
}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 是否开启即可接收新鲜内容。像平常一样获取即可:
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>
)
}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 最有用的场景是作为给编辑者的信号:一个确认他们正在查看草稿内容的横幅,以及退出的方法。从根布局渲染一个指示器,使其出现在每个预览页面上。
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>
)
}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,以便从缓存组件呈现预览指示器。缓存绕过仍然适用,因此组件会在每次草稿请求时使用新鲜数据重新执行。
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>
)
}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 进行分支:
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()
}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()
}缓存绕过仍然适用于两个分支;该分支只决定从何处读取。