VitePress 站内搜索配置完全指南:本地全文搜索与 Algolia DocSearch 深度实践
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'
}
}
})
开启后,导航栏会出现搜索按钮,点击后弹出搜索模态框,支持键盘操作与结果高亮。官方文档站的实际效果如下图所示:
从源码看,本地搜索由 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: falsefrontmatter。另外,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 站点上落地一套生产级站内搜索。
