跳转到内容

@astrojs/ sitemap

v3.4.2 GitHub npm 更新日志

这个 Astro 集成 会在构建你的 Astro 项目时根据你的页面生成站点地图。

为什么使用 Astro Sitemap

名为“为什么使用 Astro Sitemap”的章节

站点地图是一个 XML 文件，它列出了你网站上的所有页面、视频和文件。像 Google 这样的搜索引擎会读取这个文件来更高效地抓取你的网站。要了解更多信息，请查看 Google 官方关于站点地图的建议。

对于大型多页网站，推荐使用站点地图文件。如果你不使用站点地图，大多数搜索引擎仍然能够列出你网站的页面，但站点地图是确保你的网站尽可能对搜索引擎友好的一个好方法。

有了 Astro Sitemap，你无需担心自己创建这个 XML 文件：Astro Sitemap 集成会抓取你的静态生成路由并创建站点地图文件，包括由 getStaticPaths() 生成的动态路由，如 [...slug] 或 src/pages/[lang]/[version]/info.astro。

此集成无法为SSR 模式下的动态路由生成站点地图条目。

安装

名为“安装”的章节

Astro 包含一个 astro add 命令来自动设置官方集成。如果你愿意，也可以手动安装集成。

在新的终端窗口中运行以下命令之一。

终端窗口
npx astro add sitemap

如果你遇到任何问题，请随时在 GitHub 上向我们报告，并尝试下面的手动安装步骤。

手动安装

名为“手动安装”的章节

首先，使用你的包管理器安装 @astrojs/sitemap 包。

终端窗口
npm install @astrojs/sitemap

然后，使用 integrations 属性将此集成应用到你的 astro.config.* 文件中：

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  // ...
  integrations: [sitemap()],
});

用法

名为“使用”的章节

@astrojs/sitemap 需要知道你网站部署后的 URL 来生成站点地图。

在 astro.config.mjs 中，将你的网站 URL 添加为 site 选项。该 URL 必须以 http:// 或 https:// 开头。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [sitemap()],
  // ...
});

配置好站点地图集成后，构建网站时，sitemap-index.xml 和 sitemap-0.xml 文件将被添加到你的输出目录中。

sitemap-index.xml 链接到所有编号的站点地图文件。 sitemap-0.xml 列出你网站上的页面。对于非常大的网站，可能还会有其他编号的文件，如 sitemap-1.xml 和 sitemap-2.xml。

一个双页网站生成文件的示例
sitemap-index.xml
<?xml version="1.0" encoding="UTF-8"?>
  <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://stargazers.club/sitemap-0.xml</loc>
  </sitemap>
</sitemapindex>
sitemap-0.xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
  <url>
    <loc>https://stargazers.club/</loc>
  </url>
  <url>
    <loc>https://stargazers.club/second-page/</loc>
  </url>
</urlset>

站点地图发现

名为“站点地图发现”的章节

你可以通过在你网站的 <head> 和 robots.txt 文件中添加链接，让爬虫更容易找到你的站点地图。

名为“在 <head> 中的站点地图链接”的章节

在你的网站 <head> 中添加一个指向站点地图索引文件的 <link rel="sitemap"> 元素

src/layouts/Layout.astro
<head>
  <link rel="sitemap" href="/sitemap-index.xml" />
</head>
名为“在 robots.txt 中的站点地图链接”的章节

如果你的网站有 robots.txt 文件，你可以添加站点地图索引的 URL 来帮助爬虫

public/robots.txt
User-agent: *
Allow: /


Sitemap: https://<YOUR SITE>/sitemap-index.xml

如果你想重用 astro.config.mjs 中的 site 值，你也可以动态生成 robots.txt。创建一个 src/pages/robots.txt.ts 文件，而不是在 public/ 目录中使用静态文件，并添加以下代码

src/pages/robots.txt.ts
import type { APIRoute } from 'astro';


const getRobotsTxt = (sitemapURL: URL) => `\
User-agent: *
Allow: /


Sitemap: ${sitemapURL.href}
`;


export const GET: APIRoute = ({ site }) => {
  const sitemapURL = new URL('sitemap-index.xml', site);
  return new Response(getRobotsTxt(sitemapURL));
};

配置

名为“配置”的章节

要配置此集成，请在 astro.config.mjs 中向 sitemap() 函数传递一个对象。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  integrations: [
    sitemap({
      // configuration options
    }),
  ],
});

filter

名为“filter”的章节

默认情况下，所有页面都包含在你的站点地图中。通过添加自定义 filter 函数，你可以根据 URL 过滤包含的页面。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge/',
    }),
  ],
});

该函数将对你网站上的每个页面调用。 page 函数参数是当前正在处理的页面的完整 URL，包括你的 site 域名。返回 true 将页面包含在站点地图中，返回 false 则将其排除。

要过滤多个页面，请添加带有目标 URL 的参数。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      filter: (page) =>
        page !== 'https://stargazers.club/secret-vip-lounge-1/' &&
        page !== 'https://stargazers.club/secret-vip-lounge-2/' &&
        page !== 'https://stargazers.club/secret-vip-lounge-3/' &&
        page !== 'https://stargazers.club/secret-vip-lounge-4/',
    }),
  ],
});

customPages

名为“customPages”的章节

在某些情况下，一个页面可能是你已部署网站的一部分，但不是你 Astro 项目的一部分。如果你想在站点地图中包含一个不是由 Astro 创建的页面，你可以使用这个选项。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      customPages: ['https://stargazers.club/external-page', 'https://stargazers.club/external-page2'],
    }),
  ],
});

entryLimit

名为“entryLimit”的章节

每个站点地图文件的最大条目数。默认值为 45000。如果你有更多条目，则会创建一个站点地图索引和多个站点地图文件。请参阅这篇关于拆分大型站点地图的说明。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      entryLimit: 10000,
    }),
  ],
});

changefreq、lastmod 和 priority

名为“changefreq、lastmod 和 priority”的章节

这些选项对应于站点地图 XML 规范中的 <changefreq>、<lastmod> 和 <priority> 标签。

请注意，Google 会忽略 changefreq 和 priority。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      changefreq: 'weekly',
      priority: 0.7,
      lastmod: new Date('2022-02-24'),
    }),
  ],
});

serialize

名为“serialize”的章节

在写入磁盘之前为每个站点地图条目调用的函数。此函数可以是异步的。

它接收一个 SitemapItem 对象作为参数，该对象可以具有以下属性

  • url（页面的绝对 URL）。这是 SitemapItem 上唯一保证存在的属性。
  • changefreq
  • lastmod（ISO 格式的日期，String 类型）
  • priority
  • links.

这个 links 属性包含一个 LinkItem 列表，其中包含备用页面（包括父页面）。

LinkItem 类型有两个字段：url（针对指定语言的此页面版本的完全限定 URL）和 lang（此页面版本所针对的受支持语言代码）。

serialize 函数应返回 SitemapItem，无论是否修改过。

下面的示例展示了单独添加站点地图特定属性的能力。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      serialize(item) {
        if (/exclude-from-sitemap/.test(item.url)) {
          return undefined;
        }
        if (/your-special-page/.test(item.url)) {
          item.changefreq = 'daily';
          item.lastmod = new Date();
          item.priority = 0.9;
        }
        return item;
      },
    }),
  ],
});

i18n

名为“i18n”的章节

要本地化站点地图，请向此 i18n 选项传递一个对象。

此对象有两个必需属性

  • defaultLocale：String。其值必须作为 locales 的键之一存在。
  • locales：Record<String, String>，键/值对。键用于在页面路径中查找区域设置部分。值是语言属性，只允许英文字母和连字符。

阅读更多关于语言属性的内容.

阅读更多关于本地化的内容.

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      i18n: {
        defaultLocale: 'en', // All urls that don't contain `es` or `fr` after `https://stargazers.club/` will be treated as default locale, i.e. `en`
        locales: {
          en: 'en-US', // The `defaultLocale` value must present in `locales` keys
          es: 'es-ES',
          fr: 'fr-CA',
        },
      },
    }),
  ],
});

生成的站点地图如下所示

sitemap-0.xml
...
  <url>
    <loc>https://stargazers.club/</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
  </url>
  <url>
    <loc>https://stargazers.club/es/</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
  </url>
  <url>
    <loc>https://stargazers.club/fr/</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/"/>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/"/>
  </url>
  <url>
    <loc>https://stargazers.club/es/second-page/</loc>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://stargazers.club/es/second-page/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://stargazers.club/fr/second-page/"/>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://stargazers.club/second-page/"/>
  </url>
...

xslURL

名为“xslURL”的章节

用于样式化和美化你的站点地图的 XSL 样式表的 URL。

设置的值可以是相对于你配置的 site URL 的本地样式表路径，也可以是到外部样式表的绝对 URL 链接。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      xslURL: '/sitemap.xsl'
    }),
  ],
});

filenameBase

名为“filenameBase”的章节

生成站点地图 XML 文件时使用的名称前缀字符串。默认值为 sitemap。

当将 Astro 站点集成到具有预先存在的站点地图文件的域中时，此选项可能很有用。

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';


export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [
    sitemap({
      filenameBase: 'astronomy-sitemap'
    }),
  ],
});

给定的配置将在 https://stargazers.club/astronomy-sitemap-0.xml 和 https://stargazers.club/astronomy-sitemap-index.xml 生成站点地图文件。

示例

名为“示例”的章节

更多集成

前端框架

适配器

其他集成

贡献 社区 赞助