搜索功能

VitePress 支持本地搜索和 Algolia 搜索两种方案。

本地搜索

本地搜索是 VitePress 内置功能，无需额外配置即可使用。

启用本地搜索

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

本地搜索配置

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        // 详细视图
        detailedView: true,
        
        // 翻译
        translations: {
          button: {
            buttonText: '搜索文档',
            buttonAriaLabel: '搜索文档'
          },
          modal: {
            noResultsText: '没有找到结果',
            resetButtonTitle: '清除搜索',
            footer: {
              selectText: '选择',
              navigateText: '切换',
              closeText: '关闭'
            }
          }
        },
        
        // miniSearch 配置
        miniSearch: {
          searchOptions: {
            fuzzy: 0.2,
            prefix: true,
            boost: { title: 4, text: 2, titles: 1 }
          }
        }
      }
    }
  }
})

排除页面

从搜索结果中排除特定页面：

---
search: false
---

或通过 Frontmatter：

---
search:
  exclude: true
---

Algolia 搜索

Algolia 提供更强大的搜索能力，适合大型文档站点。

配置 Algolia

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        
        // 搜索框占位符
        placeholder: '搜索文档',
        
        // 搜索按钮文字
        buttonText: '搜索'
      }
    }
  }
})

获取 Algolia 凭证

1. 访问 Algolia
2. 创建账号并新建应用
3. 创建索引
4. 获取 Application ID 和 Search-Only API Key

DocSearch 配置

如果使用 DocSearch：

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        
        // DocSearch 配置
        insights: true,
        
        translations: {
          button: {
            buttonText: '搜索文档',
            buttonAriaLabel: '搜索文档'
          },
          modal: {
            searchBox: {
              resetButtonTitle: '清除',
              resetButtonAriaLabel: '清除',
              cancelButtonText: '取消',
              cancelButtonAriaLabel: '取消'
            },
            startScreen: {
              recentSearchesTitle: '搜索历史',
              noRecentSearchesText: '没有搜索历史',
              saveRecentSearchButtonTitle: '保存搜索',
              removeRecentSearchButtonTitle: '移除搜索',
              favoriteSearchesTitle: '收藏',
              removeFavoriteSearchButtonTitle: '移除收藏'
            },
            errorScreen: {
              titleText: '无法获取结果',
              helpText: '请检查网络连接'
            },
            footer: {
              selectText: '选择',
              selectKeyAriaLabel: '回车键',
              navigateText: '切换',
              navigateUpKeyAriaLabel: '上箭头',
              navigateDownKeyAriaLabel: '下箭头',
              closeText: '关闭',
              closeKeyAriaLabel: 'ESC 键',
              searchByText: '搜索提供'
            },
            noResultsScreen: {
              noResultsText: '没有找到结果',
              suggestedQueryText: '尝试搜索',
              reportMissingResultsText: '认为应该有结果？',
              reportMissingResultsLinkText: '告诉我们'
            }
          }
        }
      }
    }
  }
})

禁用搜索

export default defineConfig({
  themeConfig: {
    search: false
  }
})

自定义搜索组件

使用插槽添加搜索

<!-- docs/.vitepress/theme/Layout.vue -->
<script setup>
import DefaultTheme from 'vitepress/theme'
import CustomSearch from './components/CustomSearch.vue'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #nav-bar-content-before>
      <CustomSearch />
    </template>
  </Layout>
</template>

集成第三方搜索

<!-- docs/.vitepress/theme/components/CustomSearch.vue -->
<script setup>
import { ref } from 'vue'

const query = ref('')

function search() {
  // 调用第三方搜索 API
  console.log('Searching:', query.value)
}
</script>

<template>
  <div class="custom-search">
    <input
      v-model="query"
      type="text"
      placeholder="搜索..."
      @keyup.enter="search"
    />
    <button @click="search">
      🔍
    </button>
  </div>
</template>

<style scoped>
.custom-search {
  display: flex;
  align-items: center;
  gap: 8px;
  margin-right: 12px;
}

.custom-search input {
  padding: 6px 12px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 6px;
  background: var(--vp-c-bg-soft);
}
</style>

搜索最佳实践

优化搜索体验

1. 使用清晰的标题结构：良好的标题层级有助于搜索结果分类
2. 添加描述性内容：在页面开头添加描述有助于搜索匹配
3. 使用标签和关键词：在 Frontmatter 中添加关键词

---
title: 快速开始
description: 五分钟快速上手 VitePress
keywords:
  - VitePress
  - 快速开始
  - 入门
---

# 快速开始

搜索数据缓存

本地搜索会将搜索数据缓存在浏览器中，减少重复加载：

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        // 配置缓存
        miniSearch: {
          searchOptions: {
            fuzzy: 0.2
          }
        }
      }
    }
  }
})

下一步

学习 部署与发布 来将站点发布上线。