草稿模式

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

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

Next.js 有一个名为草稿模式的功能，可以解决这个问题。以下是如何使用它的说明。

步骤 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 的后续请求将触发草稿模式，从而更改静态生成页面的行为（稍后会详细介绍）。

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

pages/api/draft.ts

// simple example for testing it manually from your browser.
export default function handler(req, res) {
  res.setDraftMode({ enable: true })
  res.end('Draft mode is enabled')
}

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

从你的 Headless CMS 安全地访问它

在实践中，你希望从你的 Headless CMS 安全地调用此 API 路由。具体步骤将因你使用的 Headless CMS 而异，但以下是你可能采取的一些常见步骤。

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

首先，你应该使用你选择的令牌生成器创建一个 secret token string（密钥令牌字符串）。此密钥只有你的 Next.js 应用程序和你的 Headless CMS 知道。此密钥可防止没有访问你的 CMS 权限的人访问草稿 URL。

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

终端

https://<your-site>/api/draft?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.setDraftMode。
然后将浏览器重定向到 slug 指定的路径。（以下示例使用 307 重定向）。

export default async (req, res) => {
  // Check the secret and next parameters
  // This secret should only be known to this API route and the CMS
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: 'Invalid token' })
  }
 
  // Fetch the headless CMS to check if the provided `slug` exists
  // getPostBySlug would implement the required fetching logic to the headless CMS
  const post = await getPostBySlug(req.query.slug)
 
  // If the slug doesn't exist prevent draft mode from being enabled
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }
 
  // Enable Draft Mode by setting the cookie
  res.setDraftMode({ enable: true })
 
  // Redirect to the path from the fetched post
  // We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
  res.redirect(post.slug)
}

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

步骤 2：更新 `getStaticProps`

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

如果你请求一个带有 getStaticProps 的页面，并且设置了 cookie（通过 res.setDraftMode），那么 getStaticProps 将在请求时调用（而不是在构建时）。

此外，它将在 context.draftMode 为 true 的 context 对象中调用。

export async function getStaticProps(context) {
  if (context.draftMode) {
    // dynamic data
  }
}

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

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

获取草稿数据

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

例如，你的 Headless 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)
  // ...
}

就是这样！如果你从你的 Headless CMS 或手动访问草稿 API 路由（带有 secret 和 slug），你现在应该能够看到草稿内容。并且如果你在不发布的情况下更新草稿，你应该能够查看草稿。

在你的 Headless CMS 上将其设置为草稿 URL 或手动访问，你应该能够看到草稿。

终端

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

草稿模式

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

从你的 Headless CMS 安全地访问它

步骤 2：更新 `getStaticProps`

获取草稿数据

更多细节

适用于 `getServerSideProps`

适用于 API 路由

每次 `next build` 构建都是唯一的