@astrojs/ sitemap

当你构建 Astro 项目时，此 Astro 整合会根据你的页面生成站点地图。

¥This Astro integration generates a sitemap based on your pages when you build your Astro project.

为什么选择 Astro Sitemap

¥Why Astro Sitemap

站点地图是一个 XML 文件，概述了站点上的所有页面、视频和文件。Google 等搜索引擎会读取此文件以更有效地抓取你的网站。请参阅 Google 自己关于站点地图的建议了解更多信息。

¥A Sitemap is an XML file that outlines all of the pages, videos, and files on your site. Search engines like Google read this file to crawl your site more efficiently. See Google’s own advice on sitemaps to learn more.

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

¥A sitemap file is recommended for large multi-page sites. If you don’t use a sitemap, most search engines will still be able to list your site’s pages, but a sitemap is a great way to ensure that your site is as search engine friendly as possible.

使用 Astro Sitemap，你不必担心自己创建此 XML 文件：Astro Sitemap 集成将抓取你静态生成的路由并创建站点地图文件，包括动态路由（例如 getStaticPaths() 生成的 [...slug] 或 src/pages/[lang]/[version]/info.astro）。

¥With Astro Sitemap, you don’t have to worry about creating this XML file yourself: the Astro Sitemap integration will crawl your statically-generated routes and create the sitemap file, including dynamic routes like [...slug] or src/pages/[lang]/[version]/info.astro generated by getStaticPaths().

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

¥This integration cannot generate sitemap entries for dynamic routes in SSR mode.

安装

¥Installation

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

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

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

¥Run one of the following commands in a new terminal window.

npx astro add sitemap

pnpm astro add sitemap

yarn astro add sitemap

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

¥If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

手动安装

¥Manual Install

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

¥First, install the @astrojs/sitemap package using your package manager.

npm install @astrojs/sitemap

pnpm add @astrojs/sitemap

yarn add @astrojs/sitemap

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

¥Then, apply the integration to your astro.config.* file using the integrations property:

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

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

用法

¥Usage

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

¥@astrojs/sitemap needs to know your site’s deployed URL to generate a sitemap.

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

¥Add your site’s URL as the site option in astro.config.mjs. This must begin with http:// or https://.

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 文件将添加到输出目录中。

¥With the sitemap integration configured, sitemap-index.xml and sitemap-0.xml files will be added to your output directory when building your site.

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

¥sitemap-index.xml links to all the numbered sitemap files. sitemap-0.xml lists the pages on your site. For extremely large sites, there may also be additional numbered files like sitemap-1.xml and sitemap-2.xml.

Example of generated files for a two-page website

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

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

站点地图发现

¥Sitemap discovery

你可以使用站点的 <head> 和 robots.txt 文件中的链接让爬虫更容易找到你的站点地图。

¥You can make it easier for crawlers to find your sitemap with links in your site’s <head> and robots.txt file.

`<head>` 中的站点地图链接

¥Sitemap link in <head>

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

¥Add a <link rel="sitemap"> element to your site’s <head> pointing to the sitemap index file:

<head>
  <link rel="sitemap" href="/sitemap-index.xml" />
</head>

`robots.txt` 中的站点地图链接

¥Sitemap link in robots.txt

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

¥If you have a robots.txt for your website, you can add the URL for the sitemap index to help crawlers:

User-agent: *
Allow: /

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

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

¥If you want to reuse the site value from astro.config.mjs, you can also generate robots.txt dynamically. Instead of using a static file in the public/ directory, create a src/pages/robots.txt.ts file and add the following code:

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));
};

配置

¥Configuration

要配置此集成，请将对象传递给 astro.config.mjs 中的 sitemap() 函数。

¥To configure this integration, pass an object to the sitemap() function in astro.config.mjs.

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

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

filter

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

¥All pages are included in your sitemap by default. By adding a custom filter function, you can filter included pages by URL.

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 将其排除。

¥The function will be called for every page on your site. The page function parameter is the full URL of the page currently under consideration, including your site domain. Return true to include the page in your sitemap, and false to leave it out.

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

¥To filter multiple pages, add arguments with target URLs.

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

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

¥In some cases, a page might be part of your deployed site but not part of your Astro project. If you’d like to include a page in your sitemap that isn’t created by Astro, you can use this option.

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

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

¥The maximum number entries per sitemap file. The default value is 45000. A sitemap index and multiple sitemaps are created if you have more entries. See this explanation of splitting up a large sitemap.

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

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

Changefreq、lastmod 和优先级

¥changefreq, lastmod, and priority

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

¥These options correspond to the <changefreq>, <lastmod>, and <priority> tags in the Sitemap XML specification.

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

¥Note that changefreq and priority are ignored by Google.

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

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

¥A function called for each sitemap entry just before writing to a disk. This function can be asynchronous.

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

¥It receives as its parameter a SitemapItem object that can have these properties:

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

此 links 属性包含备用页面（包括父页面）的 LinkItem 列表。

¥This links property contains a LinkItem list of alternate pages including a parent page.

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

¥The LinkItem type has two fields: url (the fully-qualified URL for the version of this page for the specified language) and lang (a supported language code targeted by this version of the page).

serialize 函数应该返回 SitemapItem，无论是否被触摸。

¥The serialize function should return SitemapItem, touched or not.

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

¥The example below shows the ability to add sitemap specific properties individually.

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 选项。

¥To localize a sitemap, pass an object to this i18n option.

该对象有两个必需的属性：

¥This object has two required properties:

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

阅读有关语言属性的更多信息。

¥Read more about language attributes.

了解有关本地化的更多信息。

¥Read more about localization.

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

生成的站点地图如下所示：

¥The resulting sitemap looks like this:

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

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

¥The URL of an XSL stylesheet to style and prettify your sitemap.

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

¥The value set can be either a path relative to your configured site URL for a local stylesheet, or can be an absolute URL link to an external stylesheet.

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

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

示例

¥Examples

Astro 官方网站使用 Astro Sitemap 生成它的网站地图。
使用 GitHub 上的 Astro Sitemap 浏览项目了解更多示例！

@astrojs/ sitemap

为什么选择 Astro Sitemap

安装

手动安装

用法

站点地图发现

`<head>` 中的站点地图链接

`robots.txt` 中的站点地图链接

配置

filter

customPages

entryLimit

Changefreq、lastmod 和优先级

serialize

i18n

xslURL

示例

更多集成

前端框架

@astrojs/alpinejs

@astrojs/preact

@astrojs/react

@astrojs/solid⁠-⁠js

@astrojs/svelte

@astrojs/vue

SSR 适配器

@astrojs/cloudflare

@astrojs/netlify

@astrojs/node

@astrojs/vercel

其他集成

@astrojs/db

@astrojs/markdoc

@astrojs/mdx

@astrojs/partytown

@astrojs/sitemap

@astrojs/tailwind

@astrojs/ sitemap

为什么选择 Astro Sitemap

安装

手动安装

用法

站点地图发现

<head> 中的站点地图链接

robots.txt 中的站点地图链接

配置

filter

customPages

entryLimit

Changefreq、lastmod 和优先级

serialize

i18n

xslURL

示例

更多集成

前端框架

SSR 适配器

其他集成

`<head>` 中的站点地图链接

`robots.txt` 中的站点地图链接