使用 Algolia DocSearch 实现站内全文检索

本博客站点的搜索框默认是使用 Google 搜索引擎去搜索网站内容，这里有两个问题：一是由于政策原因，国内无法访问 Google 搜索，导致此搜索功能无效；二是 Google 搜索对本站点内容的收录可能不及时、不全面，导致搜不到某些内容。

这里主要介绍 Algolia 出品的一个站内搜索工具 “DocSearch”，在软件开发圈里，很多开源软件的官网都集成了它，比如 Vue、Vite、React、Rollup、webpack 等等。

下面讲一下我的博客接入 DocSearch 的过程：

1、申请

在 Algolia 的官方网站去申请使用 DocSearch。

申请地址是：https://docsearch.algolia.com/apply/

填写你的域名和邮箱，再勾选下面三个选项，如下图：

algolia-001

然后点击 “Join the prrogram”，出现下面的界面：

algolia-002

然后 1 分钟左右吧，他们就会往你的邮箱发一封邮件，表示收到了你的申请。

之后就是继续等待了，我是大概七八个小时以后，收到了第二封邮件，告诉我一切准备就绪，按照邮件里的指示，添加 css 和 js 就可以开始使用了。

algolia-003

2、修改主题模板

官方文档地址：https://docsearch.algolia.com/docs/docsearch-v3

由于 Algolia 给我发的邮件里引用的静态资源是 jsdelivr CDN 的链接，jsdelivr 在国内不是很稳定，所以我改成了 unpkg CDN 的链接。

我使用的是 maupassant 主题，因此，先在 themes/maupassant/layout/base.pug 文件中头部的位置插入一个 div 标签：

1	<div id="docsearch"></div>

我这里是 pug 模板引擎的写法，因此看起来有点不一样，但是最后编译出来就是上面那样的 div 标签（下图）：

algolia-004

再在 themes/maupassant/source/css/style.scss 文件中写入 css 样式：

#docsearch {
  position: absolute;
  right: 0;
  top: 0;
}

实际的添加位置如下图：

algolia-005

然后在页头模板 themes/maupassant/layout/_partial/head.pug 文件中引入 css 样式文件：

1	<link rel="stylesheet" href="https://unpkg.com/@docsearch/css@3.9.0/dist/style.css" />

实际代码如下图：

algolia-006

再在页脚模板 themes/maupassant/layout/_partial/after_footer.pug 文件的最后写入 js 脚本：

<script src="https://unpkg.com/@docsearch/js@3.9.0/dist/umd/index.js">
  <script>
    docsearch({
      appId: "xxxxxxxxxx",
      apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      indexName: "username",
      insights: true,
      container: "#docsearch",
      debug: false
    });
</script>

实际代码如下：

algolia-007

这段代码可以在 Algolia 发给我们的邮件里找到，唯一需要替换的就是红框中标出来的位置。

3、验证

接下来，把网站打包部署到线上，就可以看到效果了。

algolia-008

4、修改预设配置

默认情况下，Algolia 已经给我们配置好了一切。

如果要更详细的设置，或者调整抓取参数，就用申请时填写的邮箱，在 Algolia 官网注册并登录管理后台，就能看到 Algolia 预设置的配置信息。

记住，配置信息如果看不懂的话，不要去修改，更不要删除任何东西，否则容易出问题。

我在 Algolia 的管理后台看了一下，配置的是每周检索一次博客内容。

我看有人说 Algolia 是可以配置为最小每 24 小时检索一次。

因此翻了一下官方文档，找到了配置检索频率的文档：Crawler: Schedule。

然后我就把检索频率改为了每天的凌晨 1 点，如下图：

algolia-009

看了一下实际的检索时间，是北京时间的早上 9 点，所以他们应该是按照 UTC 时区来进行检索。

5、总结

总的来说，Algolia DocSearch 接入丝滑，通过简单几步就顺利完成了。

不知道还有没有其他站内搜索方式可以用，我查了好几个，貌似都要自建服务，那就有点得不偿失。

大道至简，Algolia 做得非常好，难怪那么受众多开源软件的青睐。

2025-05-11 更新

目前本站使用的 hexo-theme-clarity 主题，已经集成了 Algolia Docsearch 站内搜索功能。

只需要完成本页面的第一节所述申请好 Algolia 接入账号，填入主题配置中即可，不需要自己动手去修改主题模板了。

End–

推荐订阅源

郭大侠的博客