草稿模式 (Draft Mode)

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

当您的页面从无头 CMS (headless CMS) 获取数据时，静态生成非常有用。但是，当您在无头 CMS 上撰写草稿并希望立即在页面上查看草稿时，这种方式就不理想了。此时您会希望 Next.js 在请求时 (request time) 而非构建时渲染这些页面，并获取草稿内容而非已发布的内容。您会希望 Next.js 仅针对这种情况绕过静态生成。

Next.js 的草稿模式 (Draft Mode) 功能可以解决这个问题。以下是使用说明。

步骤 1：创建并访问 API 路由

如果您不熟悉 Next.js 的 API 路由，请先查阅 API 路由文档。

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

在此 API 路由中，您需要在响应对象上调用 setDraftMode。

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

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

您可以通过手动创建如下 API 路由并从浏览器访问来进行测试：

pages/api/draft.ts

// 用于从浏览器手动测试的简单示例
export default function handler(req, res) {
  res.setDraftMode({ enable: true })
  res.end('草稿模式已启用')
}

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

从无头 CMS 安全访问

实际上，您会希望从无头 CMS 安全地调用此 API 路由。具体步骤会因您使用的无头 CMS 而异，但以下是一些常见的步骤。

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

首先，您应该使用您选择的令牌生成器创建一个密钥令牌字符串 (secret token string)。此密钥仅由您的 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 中包含变量，以便 <path> 可以根据 CMS 的数据动态设置，例如：&slug=/posts/{entry.fields.slug}

最后，在草稿 API 路由中：

检查密钥是否匹配以及 slug 参数是否存在（如果不匹配或不存在，请求应失败）。
调用 res.setDraftMode。
然后将浏览器重定向到 slug 指定的路径（以下示例使用了 307 重定向）。

export default async (req, res) => {
  // 检查密钥和 next 参数
  // 此密钥应仅由此 API 路由和 CMS 知晓
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: '无效令牌' })
  }

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

  // 如果 slug 不存在，则阻止启用草稿模式
  if (!post) {
    return res.status(401).json({ message: '无效 slug' })
  }

  // 通过设置 cookie 启用草稿模式
  res.setDraftMode({ enable: true })

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

如果成功，浏览器将被重定向到您想要查看的路径，并附带草稿模式 cookie。

步骤 2：更新 `getStaticProps`

下一步是更新 getStaticProps 以支持草稿模式。

如果您请求的页面具有 getStaticProps 并且设置了 cookie（通过 res.setDraftMode），则 getStaticProps 将在请求时 (request time)（而非构建时）被调用。

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

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

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

如果您还使用 getStaticPaths，则 context.params 也将可用。

获取草稿数据

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

例如，您的无头 CMS 可能有一个用于草稿文章的不同 API 端点。如果是这样，您可以按如下方式修改 API 端点 URL：

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>

步骤 1：创建并访问 API 路由

从无头 CMS 安全访问

步骤 2：更新 `getStaticProps`

获取草稿数据

更多详情

与 `getServerSideProps` 配合使用

与 API 路由配合使用

每次 `next build` 时唯一

On this page