跳转到内容
v5-beta

@astrojs/ sitemap

v3.2.1 GitHub npm 更新日志

此 Astro 集成 在构建你的 Astro 项目时，会根据你的页面生成一个 网站地图（Sitemap）。

为什么使用 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

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

手动安装

段落标题 手动安装

首先，使用你的包管理器安装 @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 才能生成站点地图。

将你站点的 URL 添加到 astro.config.mjs 中的 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> 中的站点地图链接

段落标题 &lt;head&gt; 中的站点地图链接

将 <link rel="sitemap"> 元素添加到站点的 <head> 中，指向站点地图索引文件：

src/layouts/Layout.astro
<head>
  <link rel="sitemap" href="/sitemap-index.xml" />
</head>

robots.txt 中的站点地图链接

段落标题 robots.txt 中的站点地图链接

如果你的网站有 robots.txt，那么你可以添加站点地图索引的 URL 以帮助抓取工具：

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


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

如果你想再次利用 astro.config.mjs 中的 site，以动态生成 robots.txt 的话。 则不要使用 public/ 目录中的静态文件，而是创建 src/pages/robots.txt.ts 文件并添加以下代码：

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({
      // 配置项
    }),
  ],
});

筛选

段落标题 筛选

在默认情况下，所有的页面都会被加入站点地图。你可以通过 filter 选项来配置哪些页面加入站点地图。

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 值。

可以通过增加参数的方式来同时应用多个筛选器。

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/',
    }),
  ],
});

自定义页面

段落标题 自定义页面

在某些情况下，某个页面可能是你的部署站点的一部分，但它不是 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'],
    }),
  ],
});

条目数限制

段落标题 条目数限制

可以通过此选项来限制存在于每个站点地图文件中最大的条目数。默认值是 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

这三个选项对应着 Sitemap XML specification 中的 <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', // 所有不包含 `es` 或 `fr` 的链接都将被视为默认语言环境，即 `en`
        locales: {
          en: 'en-US', // `defaultLocale` 的值必须在 `locales` 键中存在
          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

该 URL 是用于设计和美化站点地图 XSL 样式表的。

该 URL 设置的值可以是相对于本地样式表配置的站点 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'
    }),
  ],
});

示例

段落标题 示例

更多集成

UI 框架

SSR 适配器

其他集成

贡献

你有什么想法？

创建 GitHub Issue

向我们的团队发出问题警报的最快方法。

社区