npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

vite-plugin-geo

v0.4.0

Published

Vite, Vite+, and Astro plugin to generate sitemap.xml, llms.txt, robots.txt, and optional GEO companion files.

Readme

vite-plugin-geo

npm version CI Node.js License: MIT

English | 简体中文

面向 Vite、Vite+ 与 Astro 静态站点的构建后发现文件生成与校验工具。基于统一的构建规划管线,自动生成 sitemap.xml、robots.txt、RSS 2.0 feed.xml、llms.txt v2、页面级纯净 Markdown 镜像,以及可选的 humans.txt 与 sku.md 根清单。

能力边界声明: 本工具生成的产物仅作为机器可读的发现与抓取提示,不保证任何搜索引擎或 AI 系统抓取、索引、引用或优先展示页面,也不承诺搜索排名与流量效果。

目录

核心特性

  • Sitemap 0.9 自动生成与分片: 扫描构建 HTML 生成支持 trailingSlash 策略的标准 URL 集,超过 50,000 条 URL 或 sitemapMaxBytes(上限 50 MiB)自动拆分为分片与索引,原生兼容 @astrojs/sitemap。
  • RFC 9309 robots.txt 处理: 默认逐字节保留手写 robots.txt;校验自定义指令的控制字符与 500 KiB 体积上限,始终写入站点根目录。
  • RSS 2.0 订阅发现: 生成包含 Atom self 链接与稳定规范 URL <guid> 的 feed.xml(支持按路径过滤、上限截断、语言覆盖与 feedByLocale 分语言输出),并向 HTML 幂等注入 discovery <link>。
  • llms.txt v2 与纯净 Markdown 镜像: 自动注入 rel="describedby" 与 rel="alternate" type="text/markdown",支持通过 llmsMdMirrorInclude / llmsMdMirrorExclude 控制生成范围;优先提取 <main> 或唯一 <article> 正文,支持 GFM 表格、块级链接卡片归一化、<details>/<summary>、data-geo-ignore、markdownStripSelectors 与单 H1 规范化,并自动剔除导航与表单噪音。
  • 多语言 hreflang 支持: 支持全局路径模板映射,或通过 hreflangFromHtml 逐页解析 HTML 声明生成 Sitemap xhtml:link。
  • 可选 humans.txt 与 sku.md(1.0.0-beta): 仅输出可验证的真实元数据与根目录纯 Markdown 商品目录入口,不编造缺失字段。
  • 静态构建诊断与只读 verify: 构建期默认输出静态页面诊断建议(audit),构建后可通过 vite-plugin-geo verify 只读校验最终 dist/ 产物,支持导出 JSON(schemaVersion: "1.0")与 SARIF 2.1.0 报告。
  • 多端一致管线: Vite / Vite+ 插件、Astro 集成与独立 CLI 共用同一套参数校验、冲突处理、路径规划与所有权识别逻辑。

环境要求

  • Node.js: ^20.19.0 || >=22.12.0(vite-plus 本身要求 ^22.18.0 || ^24.11.0 || >=26.0.0)
  • Vite: ^7.0.0 || ^8.0.0(可选 Vite peer 依赖,纯 CLI 或仅 Astro 项目无需单独安装 Vite)
  • Vite+: vite-plus ^1.x(通过 @voidzero-dev/vite-plus-core 内置 Vite 8 与 Rolldown)
  • Astro: ^7.0.0(可选 Astro peer 依赖,纯 Vite 项目无需安装 Astro)

安装

npm install -D vite-plugin-geo
pnpm add -D vite-plugin-geo
yarn add -D vite-plugin-geo
bun add -d vite-plugin-geo

在 Vite+ 工作区中安装:

vp add -D vite-plugin-geo

快速开始

Vite 项目

在 vite.config.js 中注册默认导出:

// vite.config.js
import { defineConfig } from 'vite';
import geo from 'vite-plugin-geo';

export default defineConfig({
  plugins: [
    geo({
      domain: 'https://example.com',
    }),
  ],
});

domain 必须是仅包含协议、主机和可选端口的 HTTP(S) 站点源(如 https://example.com),不得包含凭据、路径、查询参数或片段;子路径部署请使用 routeBasePath。

你也可以在项目 package.json 中配置 "domain" 字段。两处同时配置时 geo({ domain }) 优先。若 package.json 没有 domain,会改用绝对 URL 形式的 homepage(如 "homepage": "https://example.com"),同样须符合仅含站点源的规则;"." 等相对值会被忽略。以上均缺失时停止构建,防止产出错误的公开链接。

支持默认导出与命名导出:

import geo, { createGeoGeneratorPlugin, verifyGeoOutput } from 'vite-plugin-geo';

Vite 构建说明:

  • distDir 默认读取 Vite 解析后的 build.outDir,routeBasePath 默认读取 Vite base。
  • 插件声明 apply: 'build' 并在 generateBundle(enforce: 'post')通过 this.emitFile 写入产物,支持 build.write: false;当插件产物与 publicDir 文件重名时由插件输出覆盖,同时对无所有权标记的既有文件遵循 fileConflict、sitemapConflict 与 generateRobots。
  • SSR、库模式及多环境构建中的服务端环境不产出静态 HTML,会自动跳过生成;多环境构建仅基于客户端 HTML 输出生成发现文件。

Vite+ 项目

Vite+(vite-plus)通过 @voidzero-dev/vite-plus-core 内置 Vite 8 与 Rolldown,因此在 vite.config.ts 中直接注册默认导出即可,无需额外的适配器子路径入口:

// vite.config.ts
import { defineConfig, lazyPlugins } from 'vite-plus';
import geo from 'vite-plugin-geo';

export default defineConfig({
  plugins: lazyPlugins(() => [
    geo({
      domain: 'https://example.com',
    }),
  ]),
});

Vite+ 使用说明:

  • 建议使用 'vite-plus' 的 lazyPlugins(() => [...]) 包裹插件数组,避免 vp check、vp lint 与 vp fmt 在读取配置元数据阶段(VP_RESOLVING_CONFIG_METADATA=1)提前初始化插件。
  • 构建 Web 应用请使用 vp build(执行 Vite + Rolldown 构建管线);vp pack 基于 tsdown 用于打包库或独立可执行文件,不会生成 HTML 页面。
  • 由于 vite-plus 将 vite 映射为 @voidzero-dev/[email protected] 而非 vite@7/8,请保留 vp create 或 vp migrate 生成的 overrides(npm / pnpm)与 pnpm.peerDependencyRules。
  • 若 Vite+ 项目的 package.json 仅声明 vite-plus(无直接 vite 依赖),开启 generateHumans: true 时会在 humans.txt 的 Components: 中写入 vite-plus。

Astro 项目

Astro 在内部 Vite 构建结束后才落盘最终 HTML,请勿将本插件放入 vite.plugins。请在以下两种正式方式中二选一(不要同时启用)。

重要提示: Astro integrations 必须 从 'vite-plugin-geo/astro' 导入(import geo from 'vite-plugin-geo/astro')。若误将 'vite-plugin-geo' 的默认 Vite 插件导出传入 integrations,插件会在 astro:config:setup 阶段立即抛出明确的错误并提示修改导入路径。

方式一:Astro 原生集成(推荐)

// astro.config.mjs
import { defineConfig } from 'astro/config';
import geo from 'vite-plugin-geo/astro';

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

域名读取优先级依次为 geo({ domain })、Astro site、package.json.domain、绝对 URL 形式的 package.json.homepage。已配置 site 时无需重复填写 domain。

Astro 集成说明:

  • 未显式传入 prettyUrls 且 Astro build.format 为 'file' 时,vite-plugin-geo/astro 会自动关闭 prettyUrls 以匹配 .html 输出路径。
  • 未显式传入 trailingSlash 时,vite-plugin-geo/astro 会自动与 Astro 的 config.trailingSlash 保持一致('always' -> 'always'、'never' -> 'never'、'ignore' -> 'preserve')。Markdown 镜像路径始终保持 /about.md(不会变为 /about/.md)。
  • Astro 声明的重定向路由(route.type === 'redirect')及对应跳转页面会自动排除出 sitemap.xml、llms.txt、feed.xml、Markdown 镜像与构建审计。

方式二:构建后串联 CLI

{
  "domain": "https://example.com",
  "scripts": {
    "build": "astro build && vite-plugin-geo generate"
  }
}

CLI 默认扫描 dist/ 且不解析 astro.config.*。若域名仅写在 Astro site 中,请传入 --domain https://example.com(自定义输出目录或 Astro outDir 请同时传入 --dist-dir <path>)。

默认输出结构:

dist/
├── sitemap.xml
├── robots.txt
├── feed.xml
├── llms.txt
├── index.md
└── ...其他页面.md

输出文件与冲突策略

| 文件 | 默认状态 | 说明 | |---|---|---| | sitemap.xml | 开启(自动) | 收录符合 trailingSlash 策略的公开页面路由;超过 50,000 URL 或 sitemapMaxBytes 时自动分片。检测到外部 Sitemap 时默认跳过。 | | sitemap_index.xml | 按需生成 | Sitemap 触发分片且 sitemapIndex: true 时自动生成。 | | robots.txt | 自动 | 默认保留已有手写文件;无手写文件时根作用域(/)生成,非根作用域跳过;始终位于站点根路径 /robots.txt。 | | feed.xml | 开启 | 生成含 Atom self 链接的 RSS 2.0 订阅源,并向 HTML 注入 discovery <link>;支持路径过滤、条数限制、语言覆盖与按语言拆分(feedByLocale)。 | | llms.txt | 开启 | 当前 routeBasePath 单一作用域下的 llms.txt v2 索引;生成 .md 镜像时链接到对应镜像,镜像被排除时自动回退为页面 HTML 的 pageUrl。 | | *.md | 开启 | 按公开 pagePath 派生的页面 Markdown 镜像,前置 # <title> 与 > <description>,并提取净化后的 <main> 或 <article> 正文;始终使用 /about.md(不会出现 /about/.md)。 | | humans.txt | 关闭 | 仅输出显式配置或从 package.json 可确认的团队、版权与技术信息。 | | sku.md | 关闭 | 配置 skuMd 后在站点根目录生成 SKU.md 1.0.0-beta 纯 Markdown 目录清单。 |

目录输出模式与镜像命名: 在 build.format: 'directory'(或 */index.html 目录形式)且开启 prettyUrls: true 时,目录首页会直接映射到与 llms.txt 公开路径一致的镜像文件名:about/index.html -> about.md、zh/index.html -> zh.md(根目录 index.html -> index.md)。即使对 HTML 页面启用了 trailingSlash: 'always'(如 /about/、/zh/),对应的 .md 镜像依然保持 /about.md 与 /zh.md,不会附加尾部斜杠。

Markdown 镜像提取与净化: 内容提取优先选择 <main>,其次唯一 <article>,最后回退到去除站点外框的 <body>。提取前会自动剔除 [hidden]、[aria-hidden="true"]、[data-geo-ignore]、<form>、<input>、<select>、<textarea>、<button>、<nav>、[role="navigation"]、面包屑导航及 markdownStripSelectors 匹配的元素。同时将 <table> 转为标准 GFM 管道表格(支持无 <thead> 表格)、将包含块级元素的 <a> 卡片规整为干净的 [Title](href) 与正文描述并修复相邻内联元素间的粘连空格、规范分隔 <details>/<summary>,并强制每个 .md 镜像至多保留一个顶层 # 一级标题(去重匹配页面标题的首个 <h1>,并将代码块之外多余的 # 标题降级为 ##)。

RSS 订阅源使用建议: 在默认的 lastmodStrategy: 'none' 下,RSS <item> 会省略 <pubDate> 并按 URL 确定性排序。对于非博客类网站或工具站,建议显式设置 generateFeed: false,或通过 feedIncludePatterns 仅收录文章/更新日志页面(如需按发布时间排序,请同时开启 lastmodStrategy: 'git' 或 'file-mtime',或使用 lastmodResolver)。

所有权标记与冲突保护: 插件生成的产物带有精确格式的 Generated by vite-plugin-geo 标记,再次构建时按新配置更新;移除该标记即视为用户自有文件。遇到用户自有 llms.txt、feed.xml、humans.txt、sku.md 或 *.md 镜像时,fileConflict 默认 'preserve'(保留用户文件并告警,其余产物继续生成;若在生成 .md 镜像的同时保留了手写 llms.txt,构建日志会输出提醒警告,提示你手动同步 llms.txt 中的镜像链接)。设为 'error' 可在写入前报错中止,设为 'overwrite' 可显式覆盖。sitemap.xml 与 robots.txt 分别由 sitemapConflict 与 generateRobots 控制。

配置项

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | domain | string | package.json.domain,其次 package.json.homepage | 不含凭据、路径、查询参数或片段的 HTTP(S) 站点源。 | | distDir | string | Vite build.outDir | 构建输出目录(vite-plugin-geo/astro 自动读取构建目录,无需配置)。 | | routeBasePath | string | Vite 或 Astro base | 单一公开路径作用域(如 '/docs/');传完整 URL 会报错。 | | prettyUrls | boolean | true | 公开页面 URL 是否去除 .html 后缀。 | | trailingSlash | 'never' \| 'always' \| 'preserve' | 'never'(Astro 默认同步 config.trailingSlash) | 根路径及无扩展名公开 URL 的尾部斜杠策略;带扩展名的文件(.md、.html、.xml、.txt)永远不加尾部斜杠。'preserve' 会保留页面 <link rel="canonical"> 的斜杠形态。 | | lastmodStrategy | 'none' \| 'file-mtime' \| 'build' \| 'git' | 'none' | Sitemap <lastmod> 与 RSS <pubDate> 时间来源。 | | excludePatterns | string[] | ['404.html', '500.html'] | 排除页面的 glob 规则。 | | hreflang | Record<string, string> | undefined | 使用 {path} 占位符的全局多语言映射。 | | hreflangFromHtml | boolean | false | 从每页 HTML 的 rel="alternate" hreflang 提取 Sitemap xhtml:link;未声明页面回退到 hreflang。 | | generateSitemap | boolean | 自动 | 检测到外部 Sitemap 时默认关闭。 | | sitemapConflict | 'preserve' \| 'error' \| 'overwrite' | 自动 | 检测到外部 Sitemap 时的处理策略,默认保留并打印样例告警。 | | sitemapUrl | string | 自动 | robots.txt 与 llms.txt 引用的 Sitemap 地址。 | | fileConflict | 'preserve' \| 'error' \| 'overwrite' | 'preserve' | 已有用户文件时的冲突策略(适用于 llms.txt、feed.xml、humans.txt、sku.md 与 *.md)。 | | routeConflict | 'error' \| 'first' \| 'last' | 'error' | 多个 HTML 映射到同一公开路由时抛错或按顺序保留。 | | llmsMdMirror | boolean | true | 是否为缺少有效 Markdown alternate 的页面生成镜像。 | | llmsMdMirrorStyle | 'append' \| 'replace' | 'append' | 镜像命名方式:prettyUrls: false 时 append 生成 about.html.md,replace 生成 about.md。 | | llmsMdMirrorInclude | string[] | undefined | 指定需要生成 .md 镜像及 Markdown alternate 链接的页面 glob 列表;未匹配页面在 llms.txt 中回退为 HTML URL。 | | llmsMdMirrorExclude | string[] | undefined | 排除不生成 .md 镜像的页面 glob 列表;被排除页面在 llms.txt 中回退为 HTML URL。 | | markdownStripSelectors | string[] | [] | 在转换为 Markdown 镜像前额外剔除的 CSS 选择器列表(在 data-geo-ignore、表单、按钮、隐藏元素与导航剔除之外生效)。 | | llmsClassify | (page: LlmsPageInfo) => string \| null \| undefined | 自动 | 自定义 llms.txt 分区函数。 | | llmsSections | Record<string, string \| string[]> | 自动 | 按路径前缀配置 llms.txt 分区。 | | generateRobots | boolean | 自动 | 默认保留手写文件,否则仅在根作用域生成;显式 true 与手写文件冲突时抛错。 | | robotsDirectives | string[] | [] | 自定义 robots.txt 指令。 | | generateFeed | boolean | true | RSS 2.0 订阅源生成开关。 | | feedIncludePatterns | string[] | undefined | 限定纳入 RSS 订阅源的页面 glob 列表。 | | feedExcludePatterns | string[] | undefined | 从 RSS 订阅源排除的页面 glob 列表。 | | feedMaxItems | number | undefined | 每个 RSS 订阅源最多输出的 <item> 条数(正整数)。 | | feedLanguage | string | 首页 <html lang> 或 'en' | 显式指定 RSS <language> 的 BCP 47 语言标签(同时作为 feedByLocale: true 的回退语言)。 | | feedByLocale | boolean | false | 按页面语言分别生成独立的分语言 RSS 订阅源,避免多语言页面混入同一份 feed.xml。 | | generateHumans | boolean | false | humans.txt 生成开关。 | | skuMd | SkuMdOptions | undefined | SKU.md 1.0.0-beta 根清单配置。 | | audit | boolean | true | 构建期静态页面诊断开关。 | | auditFailOn | 'warning' \| 'advice' | 关闭 | 诊断达到指定级别时在写入前中止构建。 | | debug | boolean | false | 打印解析后的站点地址、排除原因、Sitemap 决策与镜像摘要。 |

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | stripPathPrefixes | string[] | ['src/pages/'] | 计算公开 URL 时剥离的源码路径前缀。 | | sourceHtmlDir | string | 'src/pages' | file-mtime 与 git 策略查找源码 HTML 的目录。 | | packageJsonPath | string \| false | './package.json' | package.json 路径;设为 false 跳过读取。 | | sitemapIndex | boolean | true | 是否允许自动分片并生成 sitemap_index.xml。 | | sitemapMaxBytes | number | 52428800 | 单个未压缩 Sitemap 分片的字节上限(最大 50 MiB)。 | | lastmodIgnore | string[] | [] | 跳过 lastmod 解析的 glob 列表。 | | lastmodResolver | (page: GeoPageModel) => Date \| string \| null \| undefined | undefined | 仅限插件 API:返回 Date 或有效 W3C Datetime 字符串;null 省略字段,undefined 回退策略,非法值直接报错。 | | skuMd.merchantName | string | 首页 <title> | 商户标题;缺失且无法从首页推导时构建失败。 | | skuMd.summary | string | 首页 description | 商户摘要;缺失且无法从首页推导时构建失败。 | | skuMd.catalog | Array<{ label: string; url: string }> | 必填 | 至少一个同源 HTTPS 目录链接。 |

已废弃的旧配置项(llmsFull、llmsCtx、llmsCtxFull、blockGoogleExtended、stability* 以及旧版 skuMd 的 catalogUrl、contentLanguage、market)均会直接抛出配置错误,不会静默忽略。

Astro 官方 Sitemap 兼容

若 Astro 项目已使用 @astrojs/sitemap,请将 sitemap() 放在 geo() 之前,确保 @astrojs/sitemap 先写出 Sitemap 文件,随后 vite-plugin-geo/astro 在 astro:build:done 扫描 dist/(若顺序相反,astro:config:done 会输出顺序告警):

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
import geo from 'vite-plugin-geo/astro';

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

插件会在 astro:build:done 阶段检查磁盘上的真实 Sitemap 产物,默认保留外部 Sitemap(打印文件名、来源、<loc> 数量与前 3 条样例),并让 robots.txt 与 llms.txt 自动指向实际检测到的 Sitemap(支持自定义 filenameBase)。如需显式接管,请同时配置 generateSitemap: true 与 sitemapConflict: 'overwrite'。

CLI 与 CI 产物校验

除了作为构建插件,也可直接通过命令行运行生成与只读校验:

# 从 dist/ 生成发现文件
npx vite-plugin-geo generate --domain https://example.com --dist-dir dist

# 使用 JSON 配置文件
npx vite-plugin-geo generate --config ./geo.config.json

# 只读校验最终 dist/ 产物(不受第三方 closeBundle 覆盖时序影响)
npx vite-plugin-geo verify --dist-dir dist --domain https://example.com
npx vite-plugin-geo verify --dist-dir dist --report json > geo-report.json
npx vite-plugin-geo verify --dist-dir dist --report sarif --report-file geo.sarif
npx vite-plugin-geo verify --dist-dir dist --fail-on-verify warning

# 生成后立即校验,并开启审计门禁
npx vite-plugin-geo generate --verify --fail-on-audit warning

verify 只读取最终 dist/ 目录而不修改任何文件,检查范围涵盖 Sitemap <loc> 数量、首页收录、构建中间前缀残留(如 /src/pages/)、.html 扩展名泄漏、重复 <loc>、<loc> 到产物文件映射、robots.txt 的 Sitemap: 一致性、canonical 对齐、llms.txt、feed.xml 与 Markdown 镜像(递归解析最多 5 层 Sitemap 索引)。当报告输出到 stdout 时,人类可读日志自动分流至 stderr,便于管道解析。

Vite+ 项目可通过 vp exec 或 vpx 调用 CLI:

vp build
vp exec vite-plugin-geo verify --dist-dir dist --domain https://example.com

在 Vite+ Monorepo 中从仓库根目录调用 CLI 时,默认读取当前目录的 ./package.json;针对子包构建产物请显式传入 --domain 或 --package-json-path:

vp build apps/web
vp exec vite-plugin-geo verify --dist-dir apps/web/dist --package-json-path apps/web/package.json

如使用 Vite Task(vite.config.ts 中的 run.tasks)并开启缓存,建议将 GEO 生成保留在 vp build(Vite 插件)内,并将 vite-plugin-geo verify 配在通过 dependsOn 串联的下游校验任务中,避免多个任务并发或二次改写同一 dist/ 文件。

GitHub Actions 接入 SARIF 示例:

- run: npm run build
- run: npx vite-plugin-geo verify --dist-dir dist --domain https://example.com --report sarif --report-file geo.sarif --fail-on-verify warning
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: geo.sarif

省略子命令时默认执行 generate。

| 参数 | 说明 | |---|---| | --domain <url> | 公开站点源,优先于 package.json.domain 与 homepage。 | | --dist-dir <path> | 构建输出目录,默认 dist。 | | --route-base-path <path> | 单一公开路径前缀。 | | --source-html-dir <path> | 源码 HTML 目录,默认 src/pages。 | | --package-json-path <path> | package.json 路径,支持 --package-json-path=false。 | | --strip-path-prefixes <list> | 逗号分隔的剥离路径前缀。 | | --exclude-patterns <list> | 逗号分隔的排除规则。 | | --trailing-slash <mode> | never、always 或 preserve(默认 never)。 | | --lastmod-strategy <value> | none、file-mtime、build 或 git。 | | --lastmod-ignore <list> | 逗号分隔的 lastmod 跳过规则。 | | --llms-md-mirror-style <value> | append 或 replace。 | | --llms-md-mirror-include <list> | 逗号分隔的 .md 镜像包含 glob 列表。 | | --llms-md-mirror-exclude <list> | 逗号分隔的 .md 镜像排除 glob 列表。 | | --markdown-strip-selectors <list> | 逗号分隔的 CSS 选择器,转换 Markdown 前从正文中剔除。 | | --robots-directives <list> | 逗号分隔的通用 robots.txt 指令。 | | --sitemap-url <path-or-url> | robots.txt / llms.txt 引用的 Sitemap 地址。 | | --sitemap-conflict <mode> | preserve、error 或 overwrite。 | | --file-conflict <mode> | preserve、error 或 overwrite(默认 preserve)。 | | --route-conflict <mode> | error、first 或 last(默认 error)。 | | --hreflang-from-html / --no-hreflang-from-html | 逐页 HTML hreflang 解析开关。 | | --fail-on-audit <level> | none、warning 或 advice(默认 none)。 | | --fail-on-verify <level> | none、error 或 warning(默认 error)。 | | --report <json\|sarif> | 输出机器可读报告(json 或 sarif)。 | | --report-file <path> | 报告写入文件路径(默认 stdout)。 | | --verify / --no-verify | generate 完成后立即执行 verify 的开关。 | | --pretty-urls / --no-pretty-urls | .html 后缀剥离开关。 | | --sitemap-index / --no-sitemap-index | Sitemap 自动拆分开关。 | | --generate-sitemap / --no-generate-sitemap | Sitemap 生成开关。 | | --generate-robots / --no-generate-robots | robots.txt 生成开关。 | | --llms-md-mirror / --no-llms-md-mirror | Markdown 镜像生成开关。 | | --generate-feed / --no-generate-feed | RSS 订阅源开关。 | | --feed-include-patterns <list> | 逗号分隔的 RSS 收录页面 glob 列表。 | | --feed-exclude-patterns <list> | 逗号分隔的 RSS 排除页面 glob 列表。 | | --feed-max-items <number> | 每个 RSS 订阅源最多包含的条目数。 | | --feed-language <tag> | 显式指定 RSS <language> 的 BCP 47 语言标签。 | | --feed-by-locale / --no-feed-by-locale | 按语言拆分生成独立 RSS 订阅源的开关。 | | --generate-humans / --no-generate-humans | humans.txt 生成开关。 | | --audit / --no-audit | 构建诊断开关(亦支持 --audit=true\|false)。 | | --debug / --no-debug | 调试摘要开关。 | | --config <path> | JSON 配置文件路径。 |

构建诊断

Vite、Astro 与 CLI 默认开启 audit: true,按页面路径与规则编号稳定输出静态检查提示,默认不中断构建、不改写页面;配置 auditFailOn(--fail-on-audit)后可作为 CI 硬门禁。

检查规则覆盖:<title> 与 meta description 缺失/重复、<html lang> 缺失或格式异常、<h1> 缺失或多个、Google canonical 指南边界下的 canonical 冲突与提示、JSON-LD 语法合法性、<img> 缺失 alt、指向 noindex 页面或本地缺失目标的链接、prettyUrls 下残留 .html 的站内链接、无入站静态链接的孤儿页面、hreflang 互指与自引用,以及发现 <link> 一致性。诊断仅检查本地构建产物,不发起网络请求,也不验证 CDN、WAF 或线上 HTTP 响应头。

常见配置示例

子路径部署与 replace 镜像

geo({
  domain: 'https://example.com',
  routeBasePath: '/docs/',
  llmsMdMirrorStyle: 'replace',
  generateRobots: false,
})

多语言站点(hreflang 与 hreflangFromHtml)

独立子域等共享相同路径形态的站点可使用全局模板:

geo({
  domain: 'https://en.example.com',
  hreflang: {
    en: 'https://en.example.com/{path}',
    'zh-CN': 'https://zh.example.com/{path}',
    'x-default': 'https://en.example.com/{path}',
  },
})

路径前缀型多语言站点(如 /about 与 /zh/about)请在每页 HTML <head> 中声明 alternate 簇并开启 hreflangFromHtml: true。

SKU.md 商户根清单

geo({
  domain: 'https://shop.example.com',
  skuMd: {
    merchantName: 'Example Store',
    summary: 'Independent tea catalog.',
    catalog: [
      {
        label: 'All products',
        url: 'https://shop.example.com/collections/all',
      },
    ],
  },
})

成熟站点仅补充内容页 Markdown 镜像

如果你的站点已经维护了自有的 sitemap.xml、robots.txt 或 llms.txt(或不需要 RSS 订阅源),可保留全部既有 SEO 产物,仅针对内容路由生成干净的 .md 镜像:

geo({
  domain: 'https://example.com',
  generateFeed: false,
  sitemapConflict: 'preserve',
  fileConflict: 'preserve',
  llmsMdMirrorInclude: ['docs/**', 'guides/**', 'blog/**'],
  markdownStripSelectors: ['.toc', '.breadcrumb', '[data-promo]'],
})

你也可以直接在页面 HTML 节点上添加 data-geo-ignore 属性,在生成 .md 镜像时跳过侧边组件或交互条:

<aside data-geo-ignore>不会写入 .md 镜像的交互组件</aside>

提示:当 fileConflict: 'preserve' 保留手写 llms.txt 并同时生成了新的 .md 镜像时,构建输出会打印一条提醒警告,提示你手动同步手写 llms.txt 中的镜像地址。

多语言 Astro 站点

在 astro.config.mjs 中务必从 'vite-plugin-geo/astro' 导入(切勿使用 'vite-plugin-geo' 默认导出):

// astro.config.mjs
import { defineConfig } from 'astro/config';
import geo from 'vite-plugin-geo/astro';

export default defineConfig({
  site: 'https://example.com',
  trailingSlash: 'always',
  integrations: [
    geo({
      hreflangFromHtml: true,
      feedIncludePatterns: ['blog/**', 'zh/blog/**'],
      feedByLocale: true,
      feedLanguage: 'en',
      excludePatterns: ['**/404.html', '500.html'],
    }),
  ],
});

多语言 Astro 配置要点:

  • trailingSlash 自动对齐: vite-plugin-geo/astro 会自动同步 Astro 的 config.trailingSlash('always' -> 'always'、'never' -> 'never'、'ignore' -> 'preserve'),而 .md 镜像始终输出为 /about.md、/zh/about.md(不会出现 /about/.md)。
  • 搭配 @astrojs/sitemap: 若同时使用 @astrojs/sitemap,请确保 sitemap() 位于 geo() 之前(integrations: [sitemap(), geo()])。默认情况下插件会保留 @astrojs/sitemap 的产物;若希望由 vite-plugin-geo 生成包含 hreflangFromHtml: true 的 Sitemap,请移除 sitemap() 或显式设置 generateSitemap: true 与 sitemapConflict: 'overwrite'。
  • 分语言 RSS 订阅源: 使用 feedIncludePatterns 排除着陆页和工具页,开启 feedByLocale: true 按语言分别生成独立订阅源而非混入同一份 feed.xml,并用 feedLanguage 提供默认语言回退。
  • 多语言 404.html: 根目录 404.html 与 500.html 默认排除;若站点额外生成了子语言错误页(如 zh/404.html、en/404.html),请将 '**/404.html' 加入 excludePatterns(并声明 noindex)避免进入发现产物,同时保留根目录 dist/404.html 以防止静态托管平台返回软 404。
  • 构建后脚本执行顺序: 先执行 astro build(在 astro:build:done 钩子内运行 vite-plugin-geo/astro)-> 再执行自定义后处理脚本(若改用 CLI 执行 vite-plugin-geo generate,请放在会修改 HTML 的后处理脚本之后)-> 最后在 CI 末尾运行 vite-plugin-geo verify,确保校验覆盖最终落盘的 dist/ 产物。

静态托管平台 Content-Type 响应头配置(_headers 与 vercel.json)

许多静态托管平台默认将 .md 返回为无 charset=utf-8 的 text/plain(或 application/octet-stream),或未为 feed.xml 设置 application/rss+xml; charset=utf-8。在启用 X-Content-Type-Options: nosniff 或站点包含非 ASCII(如中文)内容时,可能导致浏览器、RSS 阅读器或 AI 客户端乱码或拒绝解析。

Cloudflare Pages / Netlify(public/_headers):

/*.md
  Content-Type: text/markdown; charset=utf-8

/feed.xml
  Content-Type: application/rss+xml; charset=utf-8

在 Cloudflare Pages 中,* 可跨 / 匹配,因此 /*.md 会覆盖 /zh/about.md 等嵌套路径;在 Netlify 或开启 feedByLocale: true 时,如果平台按单级路径匹配 *,请补充对应的目录规则(例如 /docs/*.md、/zh/*.md 与 /zh/feed.xml)。

Vercel(vercel.json):

{
  "headers": [
    {
      "source": "/(.*)\\.md$",
      "headers": [
        { "key": "Content-Type", "value": "text/markdown; charset=utf-8" }
      ]
    },
    {
      "source": "/feed.xml",
      "headers": [
        { "key": "Content-Type", "value": "application/rss+xml; charset=utf-8" }
      ]
    }
  ]
}

若启用 feedByLocale: true 生成 /zh/feed.xml 等分语言订阅源,可补充 "source": "/:locale/feed.xml" 的 Content-Type: application/rss+xml; charset=utf-8 规则。

部署注意事项

  • 防范托管平台软 404: Cloudflare Pages 等静态平台仅在构建根目录存在 404.html 时才对未知路径返回真实 404,否则会返回 200 加首页内容。请确保产物包含 404.html,并在 CI 中接入 vite-plugin-geo verify。
  • 避免与 closeBundle 写 Sitemap 的插件混用: 本插件在 generateBundle 阶段输出产物,无法阻止其他插件在后续 closeBundle 钩子中覆盖文件;建议在 CI 中运行 verify 兜底校验。

规范契约与边界

公开规范审核快照日期:2026-08-12。

| 文件或机制 | 规范状态 | 本项目实现边界 | |---|---|---| | llms.txt v2(变更记录) | 社区开放提案,不是 IETF/W3C 标准 | 单一路径作用域索引、RFC 8288 / IANA describedby 与 Markdown alternate 链接、<main> / <article> 正文镜像 | | robots.txt(RFC 9309) | IETF Standards Track | 固定根路径 /robots.txt、手写文件保护、控制字符与 500 KiB 校验 | | Sitemap 0.9 | 行业协议,不是 IETF/W3C 标准 | 标准 URL 集、hreflang、50,000 URL / 50 MiB 自动分片,省略被搜索引擎忽略的 priority 与 changefreq | | RSS 2.0.11 | 稳定公开规范 | RSS 2.0、Atom self link、规范 URL 稳定 <guid>,无可靠时间时省略条目 pubDate | | humans.txt | 社区非正式约定 | 可选生成,仅写入可验证信息 | | SKU.md 1.0.0-beta(变更记录) | 实验性社区提案 | 可选生成根目录纯 Markdown 目录清单(上限 65,536 UTF-8 字节) |

URL 与镜像路径解析规则

| 模式 | 输入 HTML | 公开页面 URL 路径 | Markdown 镜像 | |---|---|---|---| | prettyUrls: true、trailingSlash: 'never'(默认) | about.html 或 about/index.html | /about | /about.md | | prettyUrls: true、trailingSlash: 'always' | about.html 或 about/index.html | /about/ | /about.md | | prettyUrls: true、trailingSlash: 'preserve' | docs/index.html | 与页面 <link rel="canonical"> 的尾部斜杠一致 | /docs.md | | prettyUrls: false | about.html | /about.html | /about.html.md(append)/ /about.md(replace) | | 首页 | index.html | /(始终保留;'always' 下 routeBasePath 根路径为 /docs/) | /index.md |

已审核但不生成的提案

| 提案或机制 | 审核结论 | |---|---| | IETF AIPREF | 词汇表仍处于草案阶段(draft-ietf-aipref-vocab-06),尚未成为正式 RFC。 | | Cloudflare Content Signals | 特定平台扩展指令,并非通用 IETF 标准。 | | W3C TDM Reservation Protocol | W3C Community Group Final Report,不是 W3C Recommendation。 | | ai.txt | 零散社区草案,缺乏稳定的跨平台部署共识。 | | Shopify agents.md | Shopify 店面专属约定,不适合作为通用 Vite 站点默认产物。 | | WebMCP Draft Community Group Report | 浏览器运行时 API 草案,不属于静态构建产物。 |

参与贡献

欢迎通过 GitHub Issues 与 Pull Requests 参与共建。

仓库目录结构:

vite-plugin-geo/
├── src/        # 运行时入口、核心生成管线、诊断/校验与 .d.ts 类型声明
├── tests/      # 单元测试与 Vite 7/8、Astro 7 真实构建集成测试
├── scripts/    # Vite Registry 元数据与真实消费者安装校验脚本
└── .github/    # GitHub Actions CI 工作流

本地开发使用 Bun 运行测试套件,并使用 Node.js(^20.19.0 || >=22.12.0)执行真实消费者兼容性矩阵:

# 安装依赖
bun install

# 运行完整测试与覆盖率
bun test
bun test --coverage

# 校验 Vite Plugin Registry 扩展元数据 Schema
bun run verify:registry-metadata

# 使用打包产物验证 Vite 7/8、Astro 7 与 Vite+ 1.x 真实项目安装构建(含 TypeScript 类型检查)
bun run verify:consumers

# 预览 npm 发包文件清单
npm run pack:dry-run

提交信息请遵循 Conventional Commits 规范(如 feat:、fix:、docs:、test:、chore:),并在提交前运行 git diff --check 确保无尾随空白。

更新日志

各版本详细变更与迁移指南请参阅 CHANGELOG.md。

开源协议

MIT © maxlee