v3.17

预渲染

Nuxt 允许在构建时静态渲染页面，以提高某些性能或 SEO 指标。

Nuxt 允许在构建时渲染应用中的选定页面。Nuxt 将在请求时提供预构建的页面，而不是动态生成它们。

¥Nuxt allows for select pages from your application to be rendered at build time. Nuxt will serve the prebuilt pages when requested instead of generating them on the fly.

Read more in Nuxt rendering modes.

基于爬取的预渲染

¥Crawl-based Pre-rendering

使用 nuxi generate 命令 和 Nitro 爬虫构建和预渲染你的应用。此命令类似于将 nitro.static 选项设置为 true 或运行 nuxt build --prerender 的 nuxt build。

¥Use the nuxi generate command to build and pre-render your application using the Nitro crawler. This command is similar to nuxt build with the nitro.static option set to true, or running nuxt build --prerender.

这将构建你的网站，启动一个 nuxt 实例，并默认预渲染根页面 / 以及它链接到的网站页面、它们链接到的网站页面等等。

¥This will build your site, stand up a nuxt instance, and, by default, prerender the root page / along with any of your site's pages it links to, any of your site's pages they link to, and so on.

npx nuxi generate

现在，你可以将 .output/public 目录部署到任何静态托管服务，或使用 npx serve .output/public 在本地预览。

¥You can now deploy the .output/public directory to any static hosting service or preview it locally with npx serve .output/public.

Nitro 爬虫的工作原理：

¥Working of the Nitro crawler:

  1. 加载应用根路由 (/) 的 HTML、~/pages 目录中的任何非动态页面以及 nitro.prerender.routes 数组中的任何其他路由。
  2. 将 HTML 和 payload.json 保存到 ~/.output/public/ 目录以进行静态服务。
  3. 在 HTML 中找到所有锚标记（<a href="...">），以便导航到其他路由。
  4. 对找到的每个锚点标签重复步骤 1-3，直到没有其他锚点标签可供抓取。

理解这一点很重要，因为未链接到可发现页面的页面无法自动预渲染。

¥This is important to understand since pages that are not linked to a discoverable page can't be pre-rendered automatically.

:

Read more in Docs > API > Commands > Generate#nuxi Generate.

了解更多关于 nuxi generate 命令的信息。

¥Read more about the nuxi generate command.

::

选择性预渲染

¥Selective Pre-rendering

你可以手动指定 Nitro 在构建期间将获取和预渲染的路由，或者像 /dynamic 一样在 nuxt.config 文件中忽略你不想预渲染的路由：

¥You can manually specify routes that Nitro will fetch and pre-render during the build or ignore routes that you don't want to pre-render like /dynamic in the nuxt.config file:

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ["/user/1", "/user/2"],
      ignore: ["/dynamic"],
    },
  },
});

你可以将其与 crawlLinks 选项结合使用，以预渲染一组爬虫无法像 /sitemap.xml 或 /robots.txt 那样发现的路由：

¥You can combine this with the crawlLinks option to pre-render a set of routes that the crawler can't discover like your /sitemap.xml or /robots.txt:

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ["/sitemap.xml", "/robots.txt"],
    },
  },
});

将 nitro.prerender 设置为 true 与将 nitro.prerender.crawlLinks 设置为 true 类似。

¥Setting nitro.prerender to true is similar to nitro.prerender.crawlLinks to true.

:

Read more in https://nitro.unjs.io/config#prerender.

了解更多关于 Nitro 文档中预渲染的信息。

¥Read more about pre-rendering in the Nitro documentation.

::

最后，你可以使用 routeRules 手动配置。

¥Lastly, you can manually configure this using routeRules.

nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Set prerender to true to configure it to be prerendered
    "/rss.xml": { prerender: true },
    // Set it to false to configure it to be skipped for prerendering
    "/this-DOES-NOT-get-prerendered": { prerender: false },
    // Everything under /blog gets prerendered as long as it
    // is linked to from another page
    "/blog/**": { prerender: true },
  },
});

:

Read more in https://nitro.unjs.io/config/#routerules.

阅读更多关于 Nitro 的 routeRules 配置的内容。

¥Read more about Nitro's routeRules configuration.

::

作为一种简便方法，你也可以使用 defineRouteRules 在页面文件中进行配置。

¥As a shorthand, you can also configure this in a page file using defineRouteRules.

:

Read more in Docs > Guide > Going Further > Experimental Features#inlinerouterules.

此功能处于实验阶段，要使用它，你必须在 nuxt.config 中启用 experimental.inlineRouteRules 选项。

¥This feature is experimental and in order to use it you must enable the experimental.inlineRouteRules option in your nuxt.config.

::

pages/index.vue
<script setup>
// Or set at the page level
defineRouteRules({
  prerender: true,
});
</script>

<template>
  <div>
    <h1>Homepage</h1>
    <p>Pre-rendered at build time</p>
  </div>
</template>

这将被转换为：

¥This will be translated to:

nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    "/": { prerender: true },
  },
});

运行时预渲染配置

¥Runtime prerender configuration

prerenderRoutes

你可以在 Nuxt 上下文 运行时使用它来为 Nitro 添加更多预渲染路由。

¥You can use this at runtime within a Nuxt context to add more routes for Nitro to prerender.

pages/index.vue
<script setup>
prerenderRoutes(["/some/other/url"]);
prerenderRoutes("/api/content/article/my-article");
</script>

<template>
  <div>
    <h1>This will register other routes for prerendering when prerendered</h1>
  </div>
</template>
Read more in prerenderRoutes.

prerender:routes Nuxt Hooks

在预渲染之前调用此方法，以便注册其他路由。

¥This is called before prerendering for additional routes to be registered.

nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    async "prerender:routes"(ctx) {
      const { pages } = await fetch("https://api.some-cms.com/pages").then(
        (res) => res.json(),
      );
      for (const page of pages) {
        ctx.routes.add(`/${page.name}`);
      }
    },
  },
});

prerender:generate Nitro 钩子

¥prerender:generate Nitro hook

在预渲染期间，每个路由都会调用此方法。你可以使用它来对每个预渲染的路由进行细粒度处理。

¥This is called for each route during prerendering. You can use this for fine grained handling of each route that gets prerendered.

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    hooks: {
      "prerender:generate"(route) {
        if (route.route?.includes("private")) {
          route.skip = true;
        }
      },
    },
  },
});