Algolia DocSearch 配置指南

如何为Docusaurus网站配置Algolia搜索功能

简介

Algolia DocSearch 是一个强大的文档搜索服务，可以为技术文档网站提供高质量的搜索体验。本指南将帮助你为 Docusaurus 网站配置 Algolia 搜索功能。

步骤 1: 注册 Algolia 账号

访问 Algolia 官网并注册一个账号
登录后，创建一个新的应用程序（Application）
记下你的应用程序 ID（Application ID）

步骤 2: 申请 DocSearch 爬虫或设置自己的爬虫

选项 A: 申请官方 DocSearch 爬虫（推荐）

访问 DocSearch 申请页面
填写表单，提供你的网站 URL 和其他必要信息
提交申请后，Algolia 团队会审核你的申请
如果申请被接受，你将收到一封包含配置信息的电子邮件

选项 B: 设置自己的爬虫

如果你想自己管理爬虫，可以按照以下步骤操作：

安装 DocSearch 爬虫：
终端窗口
```
npm install @docsearch/scraper
```

创建配置文件 docsearch.config.json：

{
  "index_name": "你的索引名称",
  "start_urls": ["https://你的网站域名/"],
  "sitemap_urls": ["https://你的网站域名/sitemap.xml"],
  "sitemap_alternate_links": true,
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".menu__link--sublist.menu__link--active",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "article h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "lvl5": "article h5, article td:first-child",
    "text": "article p, article li, article td:last-child"
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": ["language", "version", "type", "docusaurus_tag"],
    "attributesToRetrieve": ["hierarchy", "content", "anchor", "url", "url_without_anchor", "type"]
  }
}

在 Algolia 控制面板中创建 API 密钥：
- 导航到 API Keys 页面
- 创建一个新的 API 密钥，具有以下权限：
  - search
  - addObject
  - deleteObject
  - deleteIndex
  - settings
  - editSettings

运行爬虫：

docker run -it --env-file=.env -e "CONFIG=$(cat docsearch.config.json | jq -r tostring)" algolia/docsearch-scraper

其中 .env 文件包含：

APPLICATION_ID=你的应用ID
API_KEY=你的管理API密钥

步骤 3: 配置 Docusaurus

安装 Algolia 搜索主题：

npm install --save @docusaurus/theme-search-algolia

在 docusaurus.config.ts 中配置 Algolia：

export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      appId: '你的应用ID',           // 你的 Algolia 应用 ID
      apiKey: '你的搜索API密钥',      // 你的搜索 API 密钥（非管理 API 密钥）
      indexName: '你的索引名称',      // 你的索引名称
      contextualSearch: true,        // 启用上下文搜索
      // 可选配置
      searchParameters: {},          // 附加搜索参数
      searchPagePath: 'search',      // 搜索页面路径
    },
    // 注意：启用 Algolia 后，应注释或删除本地搜索配置
    // search: {
    //   provider: require.resolve('@easyops-cn/docusaurus-search-local'),
    //   // ...
    // },
  },
};

重启开发服务器：
终端窗口
```
npm run start
```

步骤 4: 验证搜索功能

访问你的网站
点击导航栏中的搜索图标
输入一些关键词进行搜索
验证搜索结果是否正确显示

常见问题

搜索结果为空

确保爬虫已成功运行并索引了你的网站
检查 Algolia 控制面板中的索引是否包含数据
验证 apiKey 是否为搜索 API 密钥（非管理 API 密钥）

依赖冲突

如果安装 @docusaurus/theme-search-algolia 时出现依赖冲突，可以尝试：

# 使用 --legacy-peer-deps 选项
npm install --save @docusaurus/theme-search-algolia --legacy-peer-deps

# 或使用 --force 选项
npm install --save @docusaurus/theme-search-algolia --force

本地搜索与 Algolia 搜索共存

不建议同时启用两种搜索方式，应该选择其中一种：

如果你希望使用 Algolia，请注释或删除本地搜索配置
如果你希望使用本地搜索，请注释或删除 Algolia 配置