🌍 vite-plugin-geo

一个强大的 Vite 构建后插件，自动生成 GEO / SEO / AI 友好文件，让你的网站对搜索引擎、LLM 和用户都更友好。

✨ 核心特性

• 🗺️ sitemap.xml — 自动生成搜索引擎索引，支持超过 50,000 URL 自动拆分
• 🤖 robots.txt — 灵活的爬虫策略配置
• 📰 feed.xml — RSS/Atom 订阅源，自动注入 link 标签到所有 HTML
• 📝 llms.txt — 为 LLM 提供结构化内容入口
• 📄 Markdown 镜像 — 每个 HTML 页面自动生成 .md 版本
• 🌐 多语言支持 — hreflang 多语言站点映射
• ⚡ 零配置开箱 — 合理的默认值，无需繁琐配置

📦 安装

npm i -D vite-plugin-geo

yarn add -D vite-plugin-geo

bun add -d vite-plugin-geo

🚀 快速开始

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

export default defineConfig({
  plugins: [
    createGeoGeneratorPlugin(),
  ],
});

构建完成后，dist/ 目录下会自动生成：

dist/
├── sitemap.xml
├── robots.txt
├── feed.xml
├── llms.txt
└── *.html.md  (每个 HTML 对应的 Markdown 镜像)

📄 输出文件

| 文件 | 默认 | 说明 | |------|------|------| | sitemap.xml | ✅ | 搜索引擎索引 | | robots.txt | ✅ | 爬虫策略 | | feed.xml | ✅ | RSS 订阅 + 自动注入 RSS/Atom link 标签 | | llms.txt | ✅ | LLM 内容入口 | | *.html.md | ✅ | 页面 Markdown 镜像 | | llms-full.md | ❌ | 全站 Markdown 聚合 | | humans.txt | ❌ | 团队/技术信息 | | sitemap_index.xml | 🔀 | URL 超过 50,000 时自动生成 |

⚙️ 配置项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | distDir | string | Vite build.outDir | 构建输出目录 | | routeBasePath | string | Vite config.base | URL 路径前缀 | | prettyUrls | boolean | true | 无扩展名页面 URL | | lastmodStrategy | 'file-mtime' \| 'build' | 'file-mtime' | 时间策略 | | excludePatterns | string[] | ['404.html', '500.html'] | 排除规则 | | hreflang | Record<string, string> | — | 多语言映射 | | llmsMdMirror | boolean | true | Markdown 镜像 | | llmsFull | boolean | false | 全站 Markdown | | generateFeed | boolean | true | RSS 订阅 | | generateHumans | boolean | false | humans.txt | | debug | boolean | false | 调试日志 |

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | stripPathPrefixes | string[] | ['src/pages/'] | URL 剥离前缀 | | sourceHtmlDir | string | 'src/pages' | 源码 HTML 目录 | | stabilityWaitMs | number | 1500 | 文件稳定等待 | | stabilityPollIntervalMs | number | 100 | 轮询间隔 | | stabilityRounds | number | 2 | 稳定轮次 | | packageJsonPath | string \| false | './package.json' | 站点元信息 | | sitemapIndex | boolean | true | 自动拆分 sitemap | | blockGoogleExtended | boolean | false | 屏蔽 Google-Extended | | robotsDirectives | string[] | [] | 自定义 robots 指令 |

🔧 CLI 命令

除了 Vite 插件，也可以独立运行：

# 通过包管理器
npx vite-plugin-geo generate
bunx vite-plugin-geo generate

# 常用参数
vite-plugin-geo generate \
  --dist-dir dist \
  --source-html-dir src/pages \
  --lastmod-strategy file-mtime \
  --no-generate-humans

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

本地调试（仓库内）：

node packages/vite-plugin-geo/cli.js generate

安装后使用：

./node_modules/.bin/vite-plugin-geo generate

说明：

• 普通终端里，本地安装的包不会自动加入系统 PATH
• 在 npm script、node_modules/.bin 已进 PATH 的终端，或通过 npx / yarn / bunx 执行时，可以直接用命令名
• generate 是默认命令，distDir 默认是 dist

支持的参数：

| 参数 | 说明 | |------|------| | --dist-dir <path> | 构建输出目录 | | --route-base-path <path> | URL 路径前缀 | | --source-html-dir <path> | 源码 HTML 目录 | | --lastmod-strategy <value> | 时间策略：file-mtime 或 build | | --pretty-urls / --no-pretty-urls | URL 模式开关 | | --generate-feed / --no-generate-feed | RSS 生成开关 | | --generate-humans / --no-generate-humans | humans.txt 开关 | | --config <path> | JSON 配置文件路径 |

📝 行为契约

🔗 URL 生成规则

| 模式 | 输入 | 输出 | |------|------|------| | prettyUrls: true | about.html | /about | | prettyUrls: true | docs/index.html | /docs | | prettyUrls: false | about.html | /about.html | | 首页 | index.html | / (始终) |

📰 RSS/Atom Link 注入

• 自动检测 feed 格式（RSS 2.0 / Atom）
• 根据格式注入正确的 MIME 类型
• 已存在的 link 标签会自动替换

🕐 时间来源

优先级：源码 HTML mtime → dist HTML mtime → 构建时间

💡 常见配置

基础配置

createGeoGeneratorPlugin({
  distDir: 'dist',
  packageJsonPath: './package.json',
})

多语言站点

createGeoGeneratorPlugin({
  hreflang: {
    en: 'https://example.com/{path}',
    'zh-CN': 'https://example.com/zh/{path}',
  },
})

完整功能

createGeoGeneratorPlugin({
  prettyUrls: true,
  generateFeed: true,
  generateHumans: true,
  llmsFull: true,
})