「Algolia&Hugo&LoveIt」搜索赋予灵魂

自在即为仙收录于极客

2025-03-29 约 947 字预计阅读 2 分钟

迁移博客到 Hugo 框架后，需要在 LoveIt 主题下启用搜索，并使用 Algolia 引擎。本文记录如何实现这一需求，以及在过程中遇到的问题。

缘起

随着文章越来越多，通过目录索引法定位内容越来越低效，需要有个给力的索引器，因此，我说：“要有 Algolia”。

为什么选择 algolia 而不是 lunr，这里讲的很清楚。

准备

准备工作很简单，注册一个 Algolia 账号，创建相应的应用并拿到相关的 Key。

Algolia

打开 [Algolia](https://dashboard.algolia.com/) 官网并注册，可以使用 Github 或 Google 登录。
创建一个 Application，名称可以是网站名称，如 hugo-classics.yirami.xyz。搜索方案选择 Build 免费方案（注意其用量限制）。区域选一个靠近的。最后，一路默认，进入到礼花页面即完成。
如果自动跳转到 Get Started 页面，选择右上角 Skip for now 回到主页。此时页面显示了 Application ID、Search API Key、Write API Key。
单击左侧边栏的 Data Sources，进而选择 Indices 和 Create Index。给索引起一个名字，比如 hugo_zh_cn 用以区分不同的网站语言。自此，索引名称也有了。

搞起

主题配置

主题选用 LoveIt，下载最新的主题后，从 exampleSite/hugo.toml 文件中摘出 [params.search] 字段放入自己配置文件的合适位置。

# 仅列出必要的修改项，其它保持
[params.search]
  enable = true
  type = "algolia"
  contentLength = 4000  # 按需修改
  [params.search.algolia]
    index = ""  # 上一步中创建的索引名称，如："hugo_zh_cn"
    appID = ""  # 上一步中取得的`Application ID`
    searchKey = ""  # 上一步中取得的`Search API Key`

此外，依据主题说明还需要确认 [outputs] 字段中输出 JSON，它会确保网站构建完成后在 public 目录下出现 index.json。

索引上传

这一步需要使用 Algolia 官方工具，需要注意老工具似乎已经不好使了。

从 Release 下载工具并安装。需根据运行环境下载对应版本，如 algolia_?.?.?_linux_arm64.deb。
```
sudo dpkg -i /path/to/algolia_?.?.?_linux_arm64.deb
```

参考工具文档，需要上传 ndjson 文件，而 Hugo 和 LoveIt 暂不支持直接输出该格式，因此需要转换一下。

sudo apt-get install -y jq  # Github Actions 已默认安装
jq -c '.[]' hugo/public/index.json > hugo/public/index.ndjson

上传索引文件。注意：命令中需要替换三处内容。

algolia objects import <your_index_name> \
    -F hugo/public/index.ndjson \
    --application-id <Application ID> \
    --api-key <Write API Key> \
    --auto-generate-object-id-if-not-exist \
    --batch-size 1000

Troubleshoot

错误使用弃用工具 @algolia/cli，会在上传时出现 “Estimating network speed…Speed test error Error: No server found, verify your proxy/network” 的错误。可以选择最新的官方工具。
Algolia 在协议中禁止免费用户上传过大的 Record，否则会出 “could not send intermediate batch: Algolia API error [400] Record at the position … is too big."。可以调小网站配置 [params.search] 中的 contentLength 字段。