前言

在 Hexo 博客中使用 Butterfly 主题开启搜索功能有两种主要方式：本地搜索（Local Search） 和 Algolia 搜索。以下是针对这两种方法的详细步骤说明。

本地搜索（Local Search）

本地搜索是通过插件生成搜索索引，在用户访问博客时进行站内搜索，无需依赖外部服务，适合简单使用场景。

安装必要的插件

你需要安装 hexo-generator-search 插件来生成搜索索引。打开终端，进入你的 Hexo 博客根目录，运行以下命令：

1
npm install hexo-generator-search --save

配置 Hexo 主配置文件

在 Hexo 根目录下的 _config.yml 文件中，添加或修改以下内容以启用搜索插件：

1
2
3
4
5
search:
  path: search.xml
  field: post
  content: true
  format: html
  • path: 搜索索引文件的生成路径，默认是 search.xml。
  • field: 指定生成索引的内容范围，可选 post（仅文章）、page（仅页面）或 all（全部）。
  • content: 是否包含文章内容，设为 true 表示搜索时会匹配文章正文。
  • format: 输出格式，默认是 html，可以保持不变。

配置 Butterfly 主题

在 Hexo 根目录下的 _config.butterfly.yml（Butterfly 主题配置文件）中，找到 search 配置项，启用本地搜索并设置相关参数：

1
2
3
4
5
6
7
search:
  enable: true
  type: local
  placeholder: 输入关键词搜索
  # 可选：自定义其他参数
  preload: true        # 是否预加载搜索索引
  top_n_per_article: 1 # 每篇文章返回的匹配结果数量
  • enable: true: 开启搜索功能。
  • type: local: 指定使用本地搜索。
  • placeholder: 搜索框内的提示文字，可自定义。
  • preload: true: 页面加载时预加载搜索索引，提升搜索速度。
  • top_n_per_article: 每篇文章返回的最大匹配结果数，默认是 1。

生成并测试

运行以下命令清理并重新生成博客文件：

1
hexo clean && hexo generate

然后启动本地服务器预览效果：

1
hexo server

打开浏览器，访问 http://localhost:4000，检查博客顶部或指定位置是否出现搜索框，并测试搜索功能是否正常工作。

Algolia 搜索

Algolia 是一种更强大的云端搜索服务，适合需要高效搜索体验的博客，但需要注册账号并配置 API 密钥。

安装 Algolia 插件

安装 hexo-algolia 插件，用于将博客内容上传到 Algolia 服务。运行以下命令：

1
npm install hexo-algolia --save

注册 Algolia 并获取密钥

  • 访问 Algolia 官网，注册一个免费账号（免费额度通常够个人博客使用）。
  • 创建一个新应用（Application），记录下以下信息：
    • Application ID
    • Search-Only API Key（用于前端搜索）
    • Admin API Key（用于上传数据）
  • 在 Algolia 仪表盘中创建一个新的索引（Index），例如命名为 hexo。

配置 Hexo 主配置文件

在 _config.yml 中添加 Algolia 相关设置：

1
2
3
4
5
algolia:
  appId: 你的 Application ID
  apiKey: 你的 Admin API Key
  indexName: 你的索引名称（如 hexo）
  chunkSize: 5000 # 可选，分块上传大小
  • appId: 从 Algolia 仪表盘获取。
  • apiKey: 使用 Admin API Key（注意安全，不要公开）。
  • indexName: 你创建的索引名称。

配置 Butterfly 主题

在 _config.butterfly.yml 中启用 Algolia 搜索：

1
2
3
4
5
6
7
8
search:
  enable: true
  type: algolia
  placeholder: 输入关键词搜索
  algolia:
    appId: 你的 Application ID
    apiKey: 你的 Search-Only API Key
    indexName: 你的索引名称（如 hexo）
  • type: algolia: 指定使用 Algolia 搜索。
  • appId: 与 _config.yml 中的一致。
  • apiKey: 使用 Search-Only API Key（仅用于前端查询，安全性较高）。
  • indexName: 与 _config.yml 中的一致。

上传数据到 Algolia

运行以下命令将博客内容上传到 Algolia：

1
hexo algolia

如果提示需要设置环境变量，可以在命令前添加：

1
HEXO_ALGOLIA_INDEXING_KEY=你的 Admin API Key hexo algolia

生成并测试

清理并生成博客文件，然后启动本地服务器：

1
2
hexo clean && hexo generate
hexo server

访问 http://localhost:4000，测试搜索框是否能返回 Algolia 的搜索结果。

常见问题与解决

  1. 搜索框不显示

    • 检查 _config.butterfly.yml 中的 search.enable 是否为 true。
    • 确保安装了正确的渲染器：npm install hexo-renderer-pug hexo-renderer-stylus。

  2. 本地搜索无结果

    • 确认 search.xml 文件已生成（在 public 文件夹中）。
    • 检查插件是否正确安装并配置。

  3. Algolia 搜索失败

    • 确保 API 密钥和索引名称无误。
    • 检查网络连接，Algolia 服务可能受限于部分地区。

选择建议

  • 本地搜索：简单易用，无需外部服务，适合小型博客或离线环境。
  • Algolia 搜索：功能强大，搜索速度快，适合需要高级搜索体验的博客，但需要额外配置和网络支持。