@adamcikado/sitemap 中文文档教程

Question

Sitemap Module

为 Nuxt.js 项目自动生成或提供动态 sitemap.xml！

发行说明

Features

• Module based on the awesome sitemap.js package ❤️
• Create sitemap or sitemap index
• Automatically add the static routes to each sitemap
• Support i18n routes from nuxt-i18n (latest version)
• Works with all modes (SSR, SPA, generate)
• For Nuxt 2.x and higher

---

Table of Contents

• Install
• Setup
• Usage
• Sitemap Options
• Sitemap Index Options
• Routes Declaration
• Hooks

Installation

npm install @nuxtjs/sitemap

或

yarn add @nuxtjs/sitemap

Setup

将 @nuxtjs/sitemap 添加到 nuxt.config.js 的 modules 部分> 文件：

{
  modules: [
    '@nuxtjs/sitemap'
  ],
}

注意：
如果您使用其他模块（例如 nuxt-i18n），请始终在数组末尾声明站点地图模块
例如。 modules: ['nuxt-i18n', '@nuxtjs/sitemap']

Configuration

添加带有sitemap属性的自定义配置：

// nuxt.config.js

{
  modules: [
    '@nuxtjs/sitemap'
  ],
  sitemap: {
    // options
  },
}

参数可以是：

Object

模块选项 站点地图或站点地图索引：

{
  sitemap: {
    // ...
  },
}

Array

sitemap 或 sitemap index 项目：

{
  sitemap: [
    {
      // ...
    },
    {
      // ...
    },
  ],
}

Function

返回有效站点地图配置的函数：

{
  sitemap: function () {
    return {
      // ...
    }
  },
}

Boolean

您可以在 false：

{
  sitemap: false
}

Usage

Setup a Sitemap

默认情况下，站点地图设置为以下路径：/sitemap.xml
所有静态路由（例如 /pages/about.vue）都会自动添加到站点地图，但您可以使用 exclude 属性。
对于动态路由（例如 /pages/_id.vue），您必须使用 routes 声明它们 属性。 此选项可以是数组或函数。 此外，generate.routes 中定义的路由将自动用于站点地图。

// nuxt.config.js

{
  sitemap: {
    hostname: 'https://example.com',
    gzip: true,
    exclude: [
      '/secret',
      '/admin/**'
    ],
    routes: [
      '/page/1',
      '/page/2',
      {
        url: '/page/3',
        changefreq: 'daily',
        priority: 1,
        lastmod: '2017-06-30T13:30:00.000Z'
      }
    ]
  }
}

Setup a Sitemap Index

要声明站点地图索引及其链接的站点地图，请使用 sitemaps 属性。
默认情况下，站点地图索引设置为以下路径：/sitemapindex.xml
sitemaps 数组中的每一项都可以使用自己的sitemap options 进行设置。

// nuxt.config.js

{
  sitemap: {
    hostname: 'https://example.com',
    lastmod: '2017-06-30',
    sitemaps: [
      {
        path: '/sitemap-foo.xml',
        routes: ['foo/1', 'foo/2'],
        gzip: true
      }, {
        path: '/folder/sitemap-bar.xml',
        routes: ['bar/1', 'bar/2'],
        exclude: ['/**']
      }
    ]
  }
}

Setup a list of sitemaps

要声明站点地图列表，请使用 array 为每个站点地图设置自己的配置。
您可以组合站点地图和站点地图索引配置。

// nuxt.config.js

{
  sitemap: [
    {
      path: '/sitemap-products.xml',
      routes: [
        // array of URL
      ]
    }, {
      path: '/sitemap-news.xml',
      routes: () => // promise or function
    }, {
      path: '/sitemapindex.xml',
      sitemaps: [{
        // array of Sitemap configuration
      }]
    }
  }
}

Sitemap Options

routes (optional) - array | function

• Default: [] or generate.routes value from your nuxt.config.js

routes 参数遵循与 generate configuration。

另请参阅下面的路由声明示例。

path (optional) - string

• Default: /sitemap.xml

生成的站点地图的 URL 路径。

hostname (optional) - string

• Default:

1. sitemap.hostname value from your nuxt.config.js
2. build.publicPath value from your nuxt.config.js (⚠️ deprecated)
3. os.hostname() in generate or spa mode, or dynamically based on request URL (headers.host) in ssr mode

此值对于生成站点地图文件是必需的，您应该在生成 或spa 模式下明确提供它。

⚠️ build.publicPath 作为默认值的用法已弃用，并将在 v3.0 版本中删除。
要在当前版本上禁用它，请设置一个假值（例如 hostname: false）。

cacheTime (optional) - number

• Default: 1000 * 60 * 15 (15 Minutes)

定义站点地图路由的更新频率（值以毫秒为单位）。
设置负值将禁用缓存。

请注意，在每次失效后，routes 将被再次评估（参见routes declaration 部分）。

此选项仅在 ssr 模式下可用。

etag (optional) - object

• Default: render.etag value from your nuxt.config.js

在站点地图上启用 etag 缓存标头（有关可能的选项，请参阅 etag 文档）。

要禁用站点地图的 etag，请设置 etag: false

此选项仅在 ssr 模式下可用。

exclude (optional) - string array

• Default: []

exclude 参数是一个 glob 模式 的数组，用于从生成的站点地图中排除静态路由。

filter (optional) - function

• Default: undefined

如果将 filter 选项设置为函数，则所有路由都将通过它进行过滤。

此选项可用于在站点地图生成之前自定义或扩展模块的功能。

示例：

// nuxt.config.js

// Filter routes by language
{
  sitemap: {
    filter ({ routes, options }) {
      if (options.hostname === 'example.com') {
        return routes.filter(route => route.locale === 'en')
      }
      return routes.filter(route => route.locale === 'fr')
    }
  }
}

// Add a trailing slash to each route
{
  sitemap: {
    filter ({ routes }) {
      return routes.map(route => {
        route.url = `${route.url}/`
        return route
      })
    }
  }
}

gzip (optional) - boolean

• Default: false

启用使用 gzip 压缩的 .xml.gz 站点地图的创建。

xmlNs (optional) - string

• Default: undefined

通过覆盖 元素中的所有默认 xmlns 属性来设置 XML 命名空间。

// nuxt.config.js

{
  sitemap: {
    xmlNs: 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"'
  }
}

xslUrl (optional) - string

• Default: undefined

用于设置站点地图样式的 XSL 文件的 URL 路径。

trailingSlash (optional) - boolean

• Default: false

为每个路由 URL 添加尾部斜杠（例如 /page/1 => /page/1/）

注意： 避免 < href="https://support.google.com/webmasters/answer/66359">爬虫的重复内容检测，您必须在 2 个 URL 之间配置 HTTP 301 重定向（参见 redirect-module 或 nuxt-trailingslash -模块)。

i18n (optional) - string | object

• Default: undefined

配置来自 nuxt-i18n 模块的本地化路由支持。

如果配置了 i18n 选项，站点地图模块将自动在 元素中添加每个页面的默认区域设置 URL，子元素 条目列出页面的每种语言/语言环境变体，包括它本身（参见 Google 站点地图指南 ).

示例：

// nuxt.config.js

{
  modules: [
    'nuxt-i18n',
    '@nuxtjs/sitemap'
  ],
  i18n: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en'
  },
  sitemap: {
    hostname: 'https://example.com',
    // shortcut notation (basic)
    i18n: true,
    // nuxt-i18n notation (advanced)
    i18n: {
      locales: ['en', 'es', 'fr'],
      routesNameSeparator: '___'
    }
  }
}

  <url>
    <loc>https://example.com/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/es/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/fr/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/"/>
  </url>

defaults (optional) - object

• Default: {}

defaults 参数设置所有路由的默认选项。

// nuxt.config.js

{
  sitemap: {
    defaults: {
      changefreq: 'daily',
      priority: 1,
      lastmod: new Date()
    }
  }
}

查看可用选项：https://github.com/ekalinin/sitemap.js/blob/4.1.1/README.md#sitemap-item-options

Sitemap Index Options

path (optional) - string

• Default: /sitemapindex.xml

生成的站点地图索引的 URL 路径。

hostname (optional) - string

将 hostname 值设置为链接到其站点地图索引的每个站点地图。

sitemaps - array of object

• Default: []

链接到站点地图索引的站点地图配置数组。

// nuxt.config.js

{
  sitemap: {
    path: '/sitemapindex.xml',
    hostname: 'https://example.com',
    sitemaps: [
      {
        path: '/sitemap-foo.xml',
        // ...
      }, {
        path: '/folder/sitemap-bar.xml',
        // ...
      }
    ]
  }
}

<!-- generated sitemapindex.xml -->

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-foo.xml</loc>
  </sitemap>
  <sitemap>
    <loc>https://example.com/folder/sitemap-bar.xml</loc>
  </sitemap>
</sitemapindex>

查看上面的更多示例。

lastmod (optional) - string

将 lastmod 值设置为链接到其站点地图索引的每个站点地图。

此外，可以为每个链接的站点地图定义 lastmod。

// nuxt.config.js

{
  sitemap: {
    lastmod: "2020-01-01",
    sitemaps: [
      {
        path: '/sitemap-foo.xml',
        lastmod: "2020-01-02"
      }, {
        path: '/sitemap-bar.xml'
      }
    ]
  }
}

etag (optional) - object

• Default: render.etag value from your nuxt.config.js

在站点地图索引上启用 etag 缓存标头（有关可能的选项，请参阅 etag 文档）。

为站点地图索引设置禁用 etag etag: false

此选项仅在 ssr 模式下可用。

gzip (optional) - boolean

• Default: false

启用使用 gzip 压缩的 .xml.gz 站点地图索引的创建。

xmlNs (optional) - string

• Default: undefined

通过覆盖 元素中的所有默认 xmlns 属性来设置 XML 命名空间。

// nuxt.config.js

{
  sitemap: {
    xmlNs: 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"',
    sitemaps: [...]
  }
}

xslUrl (optional) - string

• Default: undefined

用于设置站点地图索引样式的 XSL 文件的 URL 路径。

Routes Declaration

默认情况下，站点地图模块会忽略动态路由。
Nuxt 无法自动提供这种复杂的路由。

例子：

-| pages/
---| index.vue  --> static route
---| about.vue  --> static route
---| users/
-----| _id.vue  --> dynamic route

如果你想让模块添加任何带有动态参数的路由，你必须设置一个动态路由数组。

例如。 在配置中为 /users/:id 添加路由：

From a static list

// nuxt.config.js

{
  sitemap: {
    routes: ['/users/1', '/users/2', '/users/3']
  }
}

From a function which returns a Promise

// nuxt.config.js

const axios = require('axios')

{
  sitemap: {
    routes: async () => {
      const { data } = await axios.get('https://jsonplaceholder.typicode.com/users')
      return data.map((user) => `/users/${user.username}`)
    }
  }
}

Hooks

钩子是 Nuxt 事件的监听器。 了解更多

您可以在某些生命周期事件上注册挂钩。

Hook	Arguments	When
sitemap:generate:before	(nuxt, sitemapOptions)	Hook on before site generation
sitemap:generate:done	(nuxt)	Hook on sitemap generation finished

License

麻省理工学院许可证

Contributors

• Nicolas Pennec
• Pooya Parsa