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.
Maintainers
Readme
vite-plugin-geo
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.txtv2 与纯净 Markdown 镜像: 自动注入rel="describedby"与rel="alternate" type="text/markdown",支持通过llmsMdMirrorInclude/llmsMdMirrorExclude控制生成范围;优先提取<main>或唯一<article>正文,支持 GFM 表格、块级链接卡片归一化、<details>/<summary>、data-geo-ignore、markdownStripSelectors与单 H1 规范化,并自动剔除导航与表单噪音。- 多语言
hreflang支持: 支持全局路径模板映射,或通过hreflangFromHtml逐页解析 HTML 声明生成 Sitemapxhtml: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-geopnpm add -D vite-plugin-geoyarn add -D vite-plugin-geobun 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默认读取 Vitebase。- 插件声明
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且 Astrobuild.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 warningverify 只读取最终 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
