跳转到内容

@astrojs/sitemap

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 add 命令行工具会自动化安装过程。在新的终端窗口中运行以下命令之一(如果不确定使用哪个包管理器,请运行第一个命令)。然后按照提示,在终端中输入 “y”(表示 “yes”)确认每个提示。

Terminal window
# 使用 NPM
npx astro add sitemap
# 使用 Yarn
yarn astro add sitemap
# 使用 PNPM
pnpm astro add sitemap

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

首先,使用你喜欢的包管理器安装 @astrojs/sitemap 包。如果你使用 npm 或不确定,可以在终端中运行:

Terminal window
npm install @astrojs/sitemap

然后,使用 integrations 属性将这个集成应用到你的 astro.config.* 文件中:

astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
// ...
integrations: [sitemap()],
// ^^^^^^^^^
});

@astrojs/sitemap 需要一个部署 / 站点 URL 用于生成。在 astro.config.* 中使用 site 属性添加你的网站 URL。这个 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()],
});

请注意,与其他配置选项不同,site 是在根 defineConfig 对象中设置的,而不是在 sitemap() 调用内部。

现在,通过 astro build 命令构建你的生产网站。你会在 dist/ 目录(或者你所设定的自定义构建目录)下找到两个文件:sitemap-index.xmlsitemap-0.xml

验证网站地图已经生成后,你可以将它们添加到网站的 <head> 和爬虫读取的 robots.txt 文件中。

src/layouts/Layout.astro
<head>
<link rel="sitemap" href="/sitemap-index.xml" />
</head>
public/robots.txt
User-agent: *
Allow: /
Sitemap: https://<YOUR SITE>/sitemap-index.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>

要配置这个集成,请给 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
// ...
sitemap({
filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge',
});

站点上的每一个页面都会被筛选。对于每一个页面,page 参数代表它的完整 URL(包括 site 域名)。若想使该页面被加入站点地图,让此函数返回 true 值。否则返回 false 值。

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

astro.config.mjs
// ...
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
// ...
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 会忽略 changefreqpriority

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

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

它的参数是一个 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 选项。

这个对象有两个必需的属性:

  • defaultLocaleString。它的值必须存在于 locales 键中之一。
  • localesRecord<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',
},
},
}),
],
});

生成的网站地图如下所示:

...
<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>
...

如果需要帮助,请查看 Discord 上的 #support 频道。我们友好的支持小组成员将在那里提供帮助!

你还可以查看我们的 Astro 集成文档 以了解更多关于集成的信息。

此软件包由 Astro 核心团队维护。欢迎提交 issue 或 PR!

有关此集成的历史更改记录,请参阅 CHANGELOG.md

其他

UI 框架

SSR 适配器

其他