跳转到内容

@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 模式 (EN) 的动态路由生成网站地图条目。

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.xmlsitemap-0.xml 文件将添加到你的输出目录中。

sitemap-index.xml 链接到所有编号的站点地图文件。 sitemap-0.xml 列出了你网站上的页面。 对于非常大的站点,可能还存在其他编号文件,例如 sitemap-1.xmlsitemap-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 文件中的链接让抓取工具更轻松地找到你的站点地图。

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

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

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

该 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 适配器

其他集成

贡献

你有什么想法?

社区