VitePress 站内搜索配置完全指南:本地全文搜索与 Algolia DocSearch 深度实践

原创2026-09-20 18:30:181,996 阅读
文章标签:前端SSR文档前端构建

VitePress 站内搜索配置完全指南:本地全文搜索与 Algolia DocSearch 深度实践

VitePress 内置两套文档站搜索方案:基于 MiniSearch 的浏览器端本地全文搜索(provider: 'local'),以及基于 Algolia DocSearch 的托管式搜索(provider: 'algolia')。本文以 docs/ko/reference/default-theme-search.md 为骨架,结合仓库源码与类型定义,系统讲解两种方案的开启方式、i18n 多语言配置、MiniSearch 调优、自定义内容渲染器,以及 Algolia Ask AI 的四种集成模式,帮助你在 .vitepress/config.ts 中一次配好符合生产要求的站内搜索。

本地搜索:一行配置开启全文检索

VitePress 借助 MiniSearch 在浏览器端构建索引,实现模糊(fuzzy)全文搜索,全程无需后端服务、无需注册第三方账号。只需在配置文件里把 themeConfig.search.provider 设为 'local':

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

开启后,导航栏会出现搜索按钮,点击后弹出搜索模态框,支持键盘操作与结果高亮。官方文档站的实际效果如下图所示:

VitePress 本地搜索模态框截图,展示关键词输入与带高亮的搜索结果列表

从源码看,本地搜索由 Vite 插件 localSearchPlugin.ts 实现:

  • 构建/开发时逐页扫描站点页面,把 Markdown 渲染为 HTML 后按标题拆分为"节"(section),每节以 页面路径#锚点 作为文档 ID 写入对应语言的 MiniSearch 索引;
  • 索引内容在开发环境下通过虚拟模块 @localSearchIndex 提供给前端,改动 .md 文件时会增量重建对应页面索引并通过 HMR 推送更新;
  • 索引按语言(locale)拆分,多语言站点各语言拥有独立索引。

搜索结果文档 ID 的格式说明

本地搜索索引中的文档 ID(即 searchOptions.filter、boostDocument 及原始索引中看到的 ID)是站点相对路径,形如 /guide/page.html#section——它不包含 base 配置项。主题在渲染结果时才会把 base 拼接上去。这一点在 default-theme-search.md(英文版) 中有明确说明,自定义搜索逻辑时需注意。

除 MiniSearch 外的其他选择

除了内置本地搜索,VitePress 官方还列出了社区插件作为备选方案:vitepress-plugin-pagefind、vitepress-plugin-typesense、vitepress-plugin-cloudflare-ai-search(详见 英文版文档)。它们各自接入不同的搜索后端,可按站点规模与部署环境取舍。

本地搜索的 i18n 多语言配置

多语言站点需要为每种语言提供搜索界面的翻译文本。配置位于 search.options.locales,键名对应语言代码;若要翻译默认语言(root)的界面,把键名设为 root 即可:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          ko: { // 若要翻译默认语言,将键名改为 `root`
            translations: {
              button: {
                buttonText: '검색',
                buttonAriaLabel: '검색'
              },
              modal: {
                displayDetails: '상세 목록 표시',
                resetButtonTitle: '검색 재설정',
                backButtonTitle: '검색 닫기',
                noResultsText: '결과가 없습니다',
                footer: {
                  selectText: '선택',
                  selectKeyAriaLabel: 'Enter',
                  navigateText: '이동',
                  navigateUpKeyAriaLabel: '위쪽 화살표',
                  navigateDownKeyAriaLabel: '아래쪽 화살표',
                  closeText: '닫기',
                  closeKeyAriaLabel: 'Esc'
                }
              }
            }
          }
        }
      }
    }
  }
})

从类型定义 default-theme.d.ts 可以看出,LocalSearchOptions 还包含两个常被忽略的开关:

  • detailedView?: boolean | 'auto'(默认 'auto'):控制搜索结果的"详细视图"。true 默认展开详细视图,false 默认收起,'auto' 默认收起但允许用户自行展开;
  • disableQueryPersistence?: boolean(默认 false):设为 true 可关闭查询词在地址栏的持久化(刷新后保留搜索词)。

深入调优 MiniSearch 索引与检索行为

本地搜索的底层是 MiniSearch,你可以通过 options.miniSearch 覆盖其索引构建参数与检索参数:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        miniSearch: {
          /**
           * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
           */
          options: {
            /* ... */
          },
          /**
           * @type {import('minisearch').SearchOptions}
           * @default
           * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
           */
          searchOptions: {
            /* ... */
          }
        }
      }
    }
  }
})

两个字段的含义与默认值如下:

字段 作用 VitePress 默认值
miniSearch.options 索引构建参数,仅开放 extractField(字段提取)、tokenize(分词器)、processTerm(词项处理)三个选项 由插件内置:fields: <a href="https://link.gitcode.com/i/66566ea15b5ba3f22411a6a65e7fcdf0" target="_blank">'title', 'titles', 'text'],storeFields: ['title', 'titles'](见 [localSearchPlugin.ts)
miniSearch.searchOptions 检索参数 { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }

默认检索参数的含义:

  • fuzzy: 0.2:允许约 20% 的模糊容错,能纠正少量拼写错误;
  • prefix: true:开启前缀匹配,输入 vitep 也能命中 vitepress;
  • boost:加权排序,标题(title)权重 4、正文(text)权重 2、层级标题链(titles)权重 1,确保标题命中排在正文命中之前。

若需为不同语言定制分词(如 CJK 分词),可在 options 中传入自定义 tokenize/processTerm。更完整的 MiniSearch 参数说明见 MiniSearch 官方文档(外部链接,仅作参考)。

自定义内容渲染器:索引前的 Markdown 预处理

默认情况下,VitePress 用内置的 markdown 渲染器把页面渲染为 HTML 后再抽取可搜索文本。你可以在 search.options 中提供 _render 函数接管这一环节:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        /**
         * @param {string} src
         * @param {import('vitepress').MarkdownEnv} env
         * @param {import('markdown-it-async')} md
         */
        async _render(src, env, md) {
          // 返回 HTML 字符串
        }
      }
    }
  }
})

需要特别说明的是:该函数在构建时运行于 Node.js 环境,且会被从客户端站点数据中剥离,因此你可以在其中安全地使用 fs、path 等 Node.js API,而不会增加客户端包体积。

从源码看,_render 的调用点在 localSearchPlugin.ts:若提供了 _render,插件直接采用其返回值;否则走默认路径 md.renderAsync(raw, env),并在此处处理 env.frontmatter?.search === false 的排除逻辑。也就是说,一旦你自定义了 _render,search: false 的 frontmatter 就需要你自己处理。

示例:从搜索结果中排除指定页面

两种常用排除方式:一是在页面 frontmatter 中写 search: false;二是用 _render 按路径前缀过滤:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.search === false) return ''
          if (env.relativePath.startsWith('some/path')) return ''
          return html
        }
      }
    }
  }
})

⚠️ 注意:一旦提供自定义 _render 函数,就必须自行处理 search: false frontmatter。另外,env 对象在 md.renderAsync 被调用前并不会完整填充,因此对 frontmatter 这类可选 env 属性的检查必须放在 md.renderAsync 之后进行。

示例:内容转换——为页面注入标题锚点

某些场景下需要把 frontmatter 中的 title 注入为 h1 标题,以便搜索结果能展示页面级标题。以下实现会在渲染结果前拼接一个 # 标题 的 HTML:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.title)
            return (await md.renderAsync(`# ${env.frontmatter.title}`)) + html
          return html
        }
      }
    }
  }
})

这里用 await md.renderAsync(...) 获取 HTML 字符串(markdown-it-async 的异步接口),再拼接返回。理解这一环节背后的原理:插件随后会用 splitPageIntoSections(localSearchPlugin.ts)按 h1~h6 标题正则把 HTML 切分成带锚点的"节",每节的标题链(titles)构成搜索的层级上下文,所以标题越完整、越规范,搜索结果的分组与定位就越准确。

切换到 Algolia DocSearch 托管搜索

如果站点规模较大或希望获得基于 Algolia 基础设施的搜索体验,可以把 provider 改为 'algolia',并在 options 中提供至少 appId、apiKey、indexName 三项凭据(需先完成 Algolia DocSearch 的接入申请):

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
})

前端交互组件是 VPAlgoliaSearchBox.vue,底层通过 docsearch.ts 解析配置、校验凭据并计算集成模式。类型定义中 AlgoliaSearchOptions extends DocSearchProps(default-theme.d.ts),即 options 中除凭据外还可传入 DocSearch 支持的全部属性(如 placeholder、facetFilters、searchParameters 等)。

Algolia 搜索的 i18n 配置

多语言站点同样可以为 Algolia 搜索提供各语言的界面翻译,配置结构与本地搜索的 translations 类似,但键更多(覆盖搜索框、错误屏、起始屏、无结果屏、结果屏等),完整示例见 docs/snippets/algolia-i18n.ts:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        locales: {
          zh: {
            translations: {
              button: {
                buttonText: '搜索',
                buttonAriaLabel: '搜索'
              },
              modal: {
                searchBox: {
                  clearButtonTitle: '清除',
                  closeButtonText: '关闭',
                  placeholderText: '搜索文档或向 AI 提问'
                  /* ... */
                }
                /* ... */
              }
            }
          }
        }
      }
    }
  }
})

需要完整翻译词表(含 Ask AI 相关文案)时,可直接参考仓库中的 algolia-i18n.ts 文件,其中的 modal.searchBox.placeholderTextAskAi、askAiScreen、newConversation、startScreen 等区块覆盖了关键词搜索与 Ask AI 两种模式的全部界面文案。Algolia 侧翻译参数的权威说明见其官方 API 文档(translations 一节)。

开启 Algolia Ask AI 能力

Ask AI 允许访问者在搜索结果中直接向 AI 提问,由 Algolia 基于你的文档索引生成回答。在 options 中传入 askAi 即可启用,两种写法等价:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        // askAi: "내-어시스턴트-ID"        // 方式一:直接传 assistantId 字符串
        // 或者
        askAi: {
          // 至少必须提供 Algolia 发放的 assistantId
          assistantId: 'XXXYYY',
          // 可选覆盖项——省略时复用顶层的 appId/apiKey/indexName
          // apiKey: '...',
          // appId: '...',
          // indexName: '...'
        }
      }
    }
  }
})

⚠️ 注意:如果你希望默认使用关键词搜索、不启用 Ask AI,请直接省略 askAi 属性。

从 docsearch.ts 的 hasAskAi 实现看,askAi 为字符串时非空即视为启用;为对象时要求提供非空 assistantId。assistantId 是 Algolia 侧为你的站点生成的助手 ID,凭据校验由 Algolia DocSearch v4.5+ 运行时完成。

Ask AI 侧边面板(Side Panel)

DocSearch v4.5+ 支持可选的 Ask AI 侧边面板。启用后默认通过 Ctrl/Cmd+I 快捷键打开。侧边面板支持浮动(floating)或内嵌(inline)两种形态,并可在 panel 中配置宽度、展开宽度、建议问题等:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            // 对应 @docsearch/sidepanel-js 的 SidepanelProps API
            panel: {
              variant: 'floating', // 或 'inline'
              side: 'right',
              width: '360px',
              expandedWidth: '580px',
              suggestedQuestions: true
            }
          }
        }
      }
    }
  }
})

两点实践细节(英文版文档有额外强调,见 default-theme-search.md):

  • 建议问题:侧边面板的建议问题要用 askAi.sidePanel.panel.suggestedQuestions 配置。Algolia 独立示例中提到的顶层 askAi.suggestedQuestions 对 VitePress 侧边面板模式无效,且不会让集成后的关键词搜索模态框在首次打开时展示建议问题;
  • 关闭快捷键:若需禁用默认的 Ctrl/Cmd+I,在 sidePanel 根级别设置 keyboardShortcuts:
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            keyboardShortcuts: {
              'Ctrl/Cmd+I': false
            }
          }
        }
      }
    }
  }
})

侧边面板的完整选项清单见 DocSearch 侧边面板 API 参考(外部文档)。

四种集成模式:auto / sidePanel / hybrid / modal

VitePress 允许通过 options.mode 精确控制关键词搜索与 Ask AI 的集成方式,从 docsearch.ts 的 resolveMode 实现可以直接印证各模式的判定逻辑:

mode 行为 判定逻辑(源码)
'auto'(默认) 配置了关键词搜索凭据则推断为 hybrid;否则若配置了 Ask AI 侧边面板则推断为 sidePanel 见 case 'auto':showKeywordSearch = hasKeywordSearch(...),useSidePanel = hasSidePanelConfig
'sidePanel' 仅强制侧边面板,隐藏关键词搜索按钮 showKeywordSearch: false, useSidePanel: true
'hybrid' 同时启用关键词搜索模态框 + Ask AI 侧边面板(要求配置关键词搜索) 未配置关键词搜索凭据时控制台打印错误提示
'modal' 把 Ask AI 保留在 DocSearch 模态框内部(即使配置了侧边面板也忽略) showKeywordSearch: hasKeyword, useSidePanel: false

关键词搜索是否可用的判定标准是 appId && apiKey && indexName 三者同时非空(hasKeywordSearch,见 docsearch.ts)。

仅使用 Ask AI(不启用关键词搜索)

若只想用 Ask AI 侧边面板、完全不要关键词搜索,可以省略顶层关键词搜索凭据,把凭据全部放在 askAi 下,并显式设置 mode: 'sidePanel':

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        mode: 'sidePanel',
        askAi: {
          assistantId: 'XXXYYY',
          appId: '...',
          apiKey: '...',
          indexName: '...',
          sidePanel: true
        }
      }
    }
  }
})

此配置下导航栏不再显示关键词搜索按钮,而是显示 Ask AI 入口(对应组件 VPNavBarAskAiButton.vue),点击后直接打开侧边面板。

配套的 Algolia 爬虫配置

要让 Algolia 索引持续跟上文档更新,需要在 Algolia 控制台配置爬虫。官方文档站使用的爬虫配置示例见 docs/snippets/algolia-crawler.js,核心要点:

new Crawler({
  appId: '...',
  apiKey: '...',
  rateLimit: 8,
  startUrls: ['https://vitepress.dev/'],
  renderJavaScript: false,
  sitemaps: [],
  exclusionPatterns: [],
  discoveryPatterns: ['https://vitepress.dev/**'],
  schedule: 'at 05:10 on Saturday',
  actions: [
    {
      indexName: 'vitepress',
      pathsToMatch: ['https://vitepress.dev/**'],
      recordExtractor: ({ $, helpers }) => {
        return helpers.docsearch({
          recordProps: {
            lvl1: '.content h1',
            content: '.content p, .content li',
            lvl0: {
              selectors: 'section.has-active div h2',
              defaultValue: 'Documentation'
            },
            lvl2: '.content h2',
            lvl3: '.content h3',
            lvl4: '.content h4',
            lvl5: '.content h5'
          },
          indexHeadings: true
        })
      }
    }
  ],
  initialIndexSettings: { /* ... */ }
})

这份配置的可复用要点:

  • recordExtractor 通过 helpers.docsearch 按 lvl0~lvl5 提取文档层级结构(对应页面标题、H1~H5 锚点),indexHeadings: true 表示标题也参与索引;
  • initialIndexSettings 定义了索引的检索属性(searchableAttributes 按 lvl0~lvl6 与 content 加权排序)、distinct 去重(按 url)、高亮标签以及 customRanking 等参数,可直接作为自建索引的起点;
  • schedule 支持 cron 表达式定时增量抓取,保持索引与线上文档同步。

总结:两种方案如何选

  • 本地搜索(local):零外部依赖、无需注册,适合中小型文档站;支持模糊匹配、多语言索引、自定义 _render 预处理与 MiniSearch 深度调优,隐私友好(索引完全在浏览器端)。
  • Algolia DocSearch(algolia):托管式搜索,适合大型文档站或需要 Ask AI 问答能力的站点;需要申请凭据并配置爬虫,多语言与 Ask AI 集成(auto/sidePanel/hybrid/modal)配置项更丰富。

配置入口统一收敛在 themeConfig.search,具体类型约束见 default-theme.d.ts,本地搜索的完整实现可继续阅读 localSearchPlugin.ts,Algolia 前端逻辑可阅读 docsearch.ts。按本文的顺序配置,即可在任意 VitePress 站点上落地一套生产级站内搜索。

登录后查看全文
vitepress