DocSearch

更新: 2026/4/24 字数: 0 字时长: 0 分钟

简述

其实也有很多热门的爬虫搜索引擎，而Algolia的 Algolia DocSearch 是直接集成在VitePress中的，我们来看看有多么强大吧

配置

我们先看一下 VitePress 官方给的配置

export default defineConfig({

  themeConfig: {
    //Algolia搜索
    search: {
      provider: 'algolia',
      options: {
        appId: '<Application ID>',
        apiKey: '<Search-Only API Key>',
        indexName: '<INDEX_NAME>',
      },
    },
  },

})

单语言修改成中文，需要配置更多语言，请参考多语言

export default defineConfig({

  themeConfig: {
    //Algolia搜索纯中文版
    search: {
      provider: 'algolia',
      options: {
        appId: '<Application ID>',
        apiKey: '<Search-Only API Key>',
        indexName: '<INDEX_NAME>',
        locales: {
          root: {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                searchBox: {
                  resetButtonTitle: '清除查询条件',
                  resetButtonAriaLabel: '清除查询条件',
                  cancelButtonText: '取消',
                  cancelButtonAriaLabel: '取消'
                },
                startScreen: {
                  recentSearchesTitle: '搜索历史',
                  noRecentSearchesText: '没有搜索历史',
                  saveRecentSearchButtonTitle: '保存至搜索历史',
                  removeRecentSearchButtonTitle: '从搜索历史中移除',
                  favoriteSearchesTitle: '收藏',
                  removeFavoriteSearchButtonTitle: '从收藏中移除'
                },
                errorScreen: {
                  titleText: '无法获取结果',
                  helpText: '你可能需要检查你的网络连接'
                },
                footer: {
                  selectText: '选择',
                  navigateText: '切换',
                  closeText: '关闭',
                  searchByText: '搜索提供者'
                },
                noResultsScreen: {
                  noResultsText: '无法找到相关结果',
                  suggestedQueryText: '你可以尝试查询',
                  reportMissingResultsText: '你认为该查询应该有结果？',
                  reportMissingResultsLinkText: '点击反馈'
                },
              },
            },
          },
        },
      },
    },
  },

})

注册

由于配置还缺关键Key，所以还需要注册账号，也方便我们后期对数据进行管理

进入 Algolia官网，点击 Login 注册账号

可以选择 NO ACCOUNT YET? ，也可以直接用GitHub和谷歌账号关联注册

注册比较简单，就不讲了

说明

网站打不开，挂一个梯子即可

使用

请按自己的需求，参照下面教程，选其一使用

使用方式	区别说明
官方申请	申请时需要提交链接、邮箱及仓库(可选) ，等待周期较长，通过后会自动爬取，直接配置使用即可
Docker 不推荐	需自备服务器且安装好docker，有一定动手能力，需要每次手动爬取。步骤繁琐本次不做演示
Github Actions 推荐	准备一个公开或者私密的仓库，配置好爬虫数据的格式，Actions自动爬取

官方申请

直接在 DocSearch官网，点 Apply 申请

填入你的网址/邮箱/仓库链接即可

说明

以前使用DocSearch必须开源，现在是可选了？这么良心？

等待跳转成功就好，没有跳转，就挂个梯子

最快等待6-7小时，慢则半个多月，在邮件中会给我们一个邀请链接，复制并打开

说明

已经注册过的，也必须从邮件这个邀请链接进去

进去后会有个弹窗按钮，点 Accept 接受即可

说明

没有弹窗的，去邮箱复制邀请链接打开就有了

这样就自动完成了Application创建，但还没有数据

在 Search - index 这里点刷新看看，有数据即可

如果索引 records 值仍为0，说明爬取数据有问题

需要登录 Algolia官方爬虫后台进行调试，点击官方帮我们申请的Application

点 Overview 进来后发现爬虫数据有的，但是Records没有值，说明数据逻辑有问题

点 Editor 进来，可以参考官方的配置对照查看问题

注意

除了指定位置，其他不要乱改，特别是apikey不要改！和你申请的apikey不是同一个用途

如果你网址有别名解析或者重定向了，也只能用你申请时的网址

官方爬虫设置

new Crawler({
  appId: '...',
  apiKey: '...',
  rateLimit: 8,
  startUrls: ['https://vitepress.dev/'],
  renderJavaScript: false,
  sitemaps: [],
  exclusionPatterns: [],
  ignoreCanonicalTo: false,
  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: '',
              defaultValue: 'Documentation'
            },
            lvl2: '.content h2',
            lvl3: '.content h3',
            lvl4: '.content h4',
            lvl5: '.content h5'
          },
          indexHeadings: true
        })
      }
    }
  ],
  initialIndexSettings: {
    vitepress: {
      attributesForFaceting: ['type', 'lang'],
      attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
      attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
      attributesToSnippet: ['content:10'],
      camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
      searchableAttributes: [
        'unordered(hierarchy_radio_camel.lvl0)',
        'unordered(hierarchy_radio.lvl0)',
        'unordered(hierarchy_radio_camel.lvl1)',
        'unordered(hierarchy_radio.lvl1)',
        'unordered(hierarchy_radio_camel.lvl2)',
        'unordered(hierarchy_radio.lvl2)',
        'unordered(hierarchy_radio_camel.lvl3)',
        'unordered(hierarchy_radio.lvl3)',
        'unordered(hierarchy_radio_camel.lvl4)',
        'unordered(hierarchy_radio.lvl4)',
        'unordered(hierarchy_radio_camel.lvl5)',
        'unordered(hierarchy_radio.lvl5)',
        'unordered(hierarchy_radio_camel.lvl6)',
        'unordered(hierarchy_radio.lvl6)',
        'unordered(hierarchy_camel.lvl0)',
        'unordered(hierarchy.lvl0)',
        'unordered(hierarchy_camel.lvl1)',
        'unordered(hierarchy.lvl1)',
        'unordered(hierarchy_camel.lvl2)',
        'unordered(hierarchy.lvl2)',
        'unordered(hierarchy_camel.lvl3)',
        'unordered(hierarchy.lvl3)',
        'unordered(hierarchy_camel.lvl4)',
        'unordered(hierarchy.lvl4)',
        'unordered(hierarchy_camel.lvl5)',
        'unordered(hierarchy.lvl5)',
        'unordered(hierarchy_camel.lvl6)',
        'unordered(hierarchy.lvl6)',
        'content'
      ],
      distinct: true,
      attributeForDistinct: 'url',
      customRanking: [
        'desc(weight.pageRank)',
        'desc(weight.level)',
        'asc(weight.position)'
      ],
      ranking: [
        'words',
        'filters',
        'typo',
        'attribute',
        'proximity',
        'exact',
        'custom'
      ],
      highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
      highlightPostTag: '</span>',
      minWordSizefor1Typo: 3,
      minWordSizefor2Typos: 7,
      allowTyposOnNumericTokens: false,
      minProximity: 1,
      ignorePlurals: true,
      advancedSyntax: true,
      attributeCriteriaComputedByMinProximity: true,
      removeWordsIfNoResults: 'allOptional'
    }
  }
})

而我这里的问题是，这里多了一个 /doc

改过之后点 Runtest 测试一下，有数据即可

可以在 Search Preview 里可以搜素看看，能用就可以了

没问题了点 Save 保存，再重新在Overview重新爬取，Records有值就代表OK了

点击index回到algolia，看数据是否同步过来

最后只剩关键key了，回到 Algolia面板，选择对应的Application，查看API Keys

这里 Application ID 和 Search API Key 是必须的两个参数

将三个参数以此填入 config.ts 配置中，本地搜索就可以使用了

Github Actions

注册好账号后，我们在面板界面新建一个 Create Application

说明

官方给我们默认建了一个，也是可以直接用，演示是便于以后独立使用

地区随便吧，差不太多，蓝色的就是可用的

说明

灰色是官方申请的时候给配的，一般是HongKong，速度差不了多少

这里快速上手直接跳过

创建完成后，我们再设置 Setting 里查看

点击 Applications

点击 Rename 重命名一下，方便之后使用

我就改成 vitepress ，保存

点击改好的，回到面板界面

点击右下角 Date Sources - Indices - Create Index 创建索引

名字随意，一会要用！

点击右上角设置 Settings - API Keys ，查看关键Keys

其中 Application ID Search-Only API Key Admin API Key 尤为重要

4个关键数据说明

Application ID：应用ID

Search-Only API Key：搜索API

Admin API Key：管理API

indexName：索引名

我们在任意仓库（公开或私密） - 设置 - Secrets and variables - actions

密钥中，新增仓库密钥 New repository secret

分别添加 APPLICATION_ID 和 API_KEY

千万不要填错了

APPLICATION_ID：是应用ID（APPLICATION ID）

API_KEY：是管理API（Admin API Key）

这样2个密钥都添加好了

然后在仓库根目录新建一个文件

命名为 docsearch.json ，格式如下，按需修改其他不要动

docsearch.json

json

{
    "index_name": "你的索引名",
    "start_urls": [
        {
            "url": "https://你的网站",
            "selectors_key": ""
        }
    ],
    "stop_urls": [],
    "selectors": {
        "default": {
            "lvl0": {
                "selector": "",
                "default_value": "我的文档"
            },
            "lvl1": ".content h1",
            "lvl2": ".content h2",
            "lvl3": ".content h3",
            "lvl4": ".content h4",
            "lvl5": ".content h5",
            "lvl6": ".content h6",
            "text": ".content p, .content li",
            "lang": {
                "selector": "/html/@lang",
                "type": "xpath",
                "global": true
            }
        }
    },
    "custom_settings": {
        "attributesForFaceting": [
            "lang"
        ]
    }
}

修改好index_name和网址后，提交即可

这样就可以了

然后在仓库，点击 Actions - set up a workflow yourself 新建一个工作流

命名为 docsearch.yml ，复制粘贴下面的工作流代码，提交

yml

name: docsearch

on:
  push:
    branches:
      - main

jobs:
  algolia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Get the content of docsearch.json as config
        id: algolia_config
        run: echo "::set-output name=config::$(cat docsearch.json | jq -r tostring)"

      - name: Run algolia/docsearch-scraper image
        env:
          APPLICATION_ID: ${{ secrets.APPLICATION_ID }}
          API_KEY: ${{ secrets.API_KEY }}
          CONFIG: ${{ steps.algolia_config.outputs.config }}
        run: |
          docker run \
            --env APPLICATION_ID=${APPLICATION_ID} \
            --env API_KEY=${API_KEY} \
            --env "CONFIG=${CONFIG}" \
            algolia/docsearch-scraper

触发方式不喜欢可以自己改

提交后触发发布后触发定时触发参考cron规则手动触发

yml

on:
  push:
    branches:
      - main

yml

on: deployment

yml

on:
  schedule:
    - cron: '0 0 * * *'

yml

on:
  workflow_dispatch:

仓库会多一个 .github/workflows 的目录

我们静等工作流跑完，如果失败，就是你密钥没有正确配置

看一下Algolia已经有数据了

我们配置在 config.mts 中，就可以使用搜索了

export default defineConfig({

  themeConfig: {
    //Algolia搜索
    search: {
      provider: 'algolia',
      options: {
        //本人的配置，供你们参考使用
        appId: 'QVKQI62L15',
        apiKey: 'bef8783dde57293ce082c531aa7c7e0c',
        indexName: 'doc',
      },
    },
  },

})

搜索美化

需要对json文件进行修改，以下是仅单独增加一个 Markdown 页面分类的简单案例

案例说明代码说明

start_urls：爬取链接，必须要一个默认主页和其他页，多页面就得多填
tags：标签，也是我们分类的最最重要的代码
stop_urls：不爬取的页面
selectors：默认一个 default 必须要有，然后再依次新增标签页
default_value：标签显示的文字，可以是中文
attributesForFaceting：必须具备 lang tags 否则有数据也用不了

注：请根据自己的页面进行新增修改！！！

json

{
    "index_name": "doc",
    "start_urls": [
        {
            "url": "https://vitepress.yiov.top/preface.html", 
            "selectors_key": "preface",
            "tags": ["preface"]
        },
        "https://vitepress.yiov.top/"
    ],
    "stop_urls": [],
    "selectors": {
      "preface": { 
            "lvl0": {
                "selector": "",
                "default_value": "前言"
            },
            "lvl1": ".content h1",
            "lvl2": ".content h2",
            "lvl3": ".content h3",
            "lvl4": ".content h4",
            "lvl5": ".content h5",
            "lvl6": ".content h6",
            "text": ".content p, .content li",
            "lang": {
                "selector": "/html/@lang",
                "type": "xpath",
                "global": true
            }
        },
        "default": {
            "lvl0": {
                "selector": "",
                "default_value": "我的文档"
            },
            "lvl1": ".content h1",
            "lvl2": ".content h2",
            "lvl3": ".content h3",
            "lvl4": ".content h4",
            "lvl5": ".content h5",
            "lvl6": ".content h6",
            "text": ".content p, .content li",
            "lang": {
                "selector": "/html/@lang",
                "type": "xpath",
                "global": true
            }
        }
    },
    "custom_settings": {
        "attributesForFaceting": [
            "lang","tags"
        ]
    }
}

最后将所有页面添加完后，对比文件，看效果

说明

如果你的页面很多，额，那是真的有点麻烦，可以不美化

DocSearch ​

简述 ​

配置 ​

注册 ​

使用 ​

官方申请 ​

Github Actions ​

搜索美化 ​

DocSearch

简述

配置

注册

使用

官方申请

Github Actions

搜索美化