搜索配置

本页是搜索功能的配置参考：三套搜索引擎（本地 / Algolia / Pagefind）各自的配置项、默认引擎的选取与切换，以及多语言结果过滤与统一高亮。使用步骤（打开弹窗、快捷键）见布局与搜索。

配置权威源为 userConfig/_config.tmp.yml 的 search 段，构建时注入主题配置。

阅读方式：每节都按「如何启用 → 常用选项 → 全部可调项 → 边界与冲突」展开，先看效果，再看产生该效果的对应配置，复制即可用。

1. 三引擎概览

用途：知道有哪三套索引，以及各自的产物落点。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

1.1 如何启用

效果：搜索弹窗打开后，输入关键词即可出现结果；弹窗内还有引擎下拉可现场切换，三种引擎结果页布局一致。

对应配置（最小可用，开启全部三套）：

search:
  default: "algolia"
  algolia:
    enable: true
  local:
    enable: true
  pagefind:
    enable: true

1.2 常用选项

① 只留本地搜索

效果：不依赖任何外部服务，索引随站内 JSON 走；首搜需要下载索引。

对应配置：

search:
  default: "local"
  local:
    enable: true
  algolia:
    enable: false
  pagefind:
    enable: false

1.3 全部可调项

1.4 边界与冲突

• 三套可同时开启，由弹窗内下拉切换；关闭某引擎后它从下拉里消失。
• Pagefind 需要构建后额外跑一次扫描（见 §5），否则该引擎无索引。
• Algolia 需要构建时推送索引，凭据分离见 §4。

1.5 小结

• 最小可用：只开 local
• 要零服务：local 或 pagefind
• 要相关性/容错：algolia
• 别只改 default 不开引擎：会自动降级

2. 默认引擎与切换

用途：决定弹窗打开时先用哪套引擎，以及读者切换后如何记忆。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

2.1 如何启用

效果：打开搜索弹窗，默认按 search.default 指定的引擎搜索；读者在下拉里换过引擎后，下次打开沿用其选择。

对应配置：

search:
  default: "local"

2.2 常用选项

① 换默认引擎

效果：弹窗首选的搜索后端变化，结果排序与匹配方式随之变化。

对应配置：

search:
  default: "pagefind"

② 让读者选择持久化

效果：切换引擎后写入 localStorage，下次免选。

对应配置：无——由前端自动完成。

2.3 全部可调项

• 生效顺序：localStorage['search_engine'] 记忆 → search.default → Algolia → 第一个已启用引擎。
• 若默认引擎 enable: false，自动降级到第一个已启用引擎并打警告日志。
• 切换入口：搜索弹窗内的引擎下拉（#searchEngineMenu，项 data-engine=local|algolia|pagefind）；切换会 destroy 旧引擎并 init 新引擎，选择写入 localStorage。

2.4 边界与冲突

• localStorage 优先级最高——改了 search.default 后老读者仍用他上次选的引擎（属预期）。
• 全部引擎都关闭时弹窗无结果，且无兜底提示。

2.5 小结

• 最小可用：default + 对应引擎 enable: true
• 改了默认没生效：先清 localStorage['search_engine']
• 降级警告：说明默认引擎没开

3. 本地搜索 search.local

用途：用主题生成的 JSON 索引在浏览器内搜索，无外部服务。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

3.1 如何启用

效果：构建产出 /search.json；打开弹窗输入即出结果（trigger: auto），命中词高亮；首次搜索需下载索引。

对应配置：

search:
  local:
    enable: true
    path: /search.json
    field: [post, wiki]
    content: true
    trigger: auto

3.2 常用选项

① 只搜标题（索引更小）

效果：索引体积明显变小、加载更快，但正文关键词搜不到。

对应配置：

search:
  local:
    content: false

② 扩大搜索范围

效果：页面（page）与 Wiki（wiki）也进入结果，而不只是文章。

对应配置：

search:
  local:
    field: all

③ 改触发方式

效果：manual 时输入不搜，需回车或点按钮才发起。

对应配置：

search:
  local:
    trigger: manual

④ 每篇片段数

效果：1 时每篇文章只展示一条命中片段，-1 展示全部。

对应配置：

search:
  local:
    top_n_per_article: -1

3.3 全部可调项

3.4 边界与冲突

• unescape / preload 是预留项，当前实现未接入，改了无效果。
• format: raw 会保留 HTML，索引体积显著变大。
• content: false 时正文关键词搜不到，只匹配标题。

3.5 小结

• 最小可用：enable: true（其余用默认）
• 索引太大：content: false 或收窄 field
• 想秒开：等 preload 接入，或改用 Pagefind
• 预留项别折腾：unescape/preload 当前无效

4. Algolia search.algolia

用途：远端索引搜索，相关性排序与容错更好，需构建时推送。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

4.1 如何启用

效果：搜索走 Algolia 服务，结果带摘要与耗时统计；索引由构建时推送，未推送则搜不到新文章。

对应配置：

search:
  algolia:
    enable: true
    applicationID: "你的 App ID"
    apiKey: "你的 Search-Only API Key"
    indexName: "blog"

4.2 常用选项

① 控制正文索引长度

效果：content_length 越大，正文可搜范围越广，但单条记录越大；超过 10KB 会被 Algolia 拒绝推送。

对应配置：

search:
  algolia:
    content_length: 2500

② 控制摘要长度

效果：结果里的摘要片段长度变化。

对应配置：

search:
  algolia:
    excerpt_length: 300

③ 每页结果数与批大小

效果：结果分页条数、构建推送的批量大小变化。

对应配置：

search:
  algolia:
    batch_size: 1000
    hits:
      per_page: 10

④ 界面文案

效果：搜索框占位符、无结果提示、结果统计文案变化。

对应配置：

search:
  algolia:
    labels:
      input_placeholder: "Search for Posts"
      hits_empty: "We didn't find any results for the search: ${query}"
      hits_stats: "${hits} results found in ${time} ms"

4.3 全部可调项

• content_length：正文纯文本截断字符数；excerpt_length：摘要截断字符数。
• batch_size：推送批大小；hits.per_page：每页结果数。
• labels.*：input_placeholder / hits_empty / hits_stats。
• 写入凭据与前端分离：构建推送用 deploy.algolia_write_key，不注入前端。

4.4 边界与冲突

• Algolia 单条记录硬上限 10KB（10240 字节），超出会被拒绝推送（HTTP 400）。中文 UTF-8 每字符 3 字节，扣去标题/标签等字段开销（约 500B）后：中文内容上限约 3000 字符，纯 ASCII 约 9000 字符。content_length: 25000 必然失败。
• apiKey 是前端搜索凭据，可安全暴露；deploy.algolia_write_key 是写凭据，只能留在构建端。
• 改了内容但没重新构建推送，搜索结果仍是旧索引。

4.5 小结

• 最小可用：enable + applicationID + apiKey + indexName
• 推送 400：content_length 太大，按 10KB 上限砍
• 新文章搜不到：索引没推送
• 别把写凭据塞进 apiKey

5. Pagefind search.pagefind

用途：构建后扫描 public/ 生成的纯静态索引，浏览器端搜索，无服务器无外网。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

5.1 如何启用

效果：public/pagefind/ 下出现索引文件，搜索完全在前端完成；加密文章不出现在结果里。

对应配置：

search:
  pagefind:
    enable: true
    output_subdir: pagefind

构建步骤：hexo generate 之后、部署之前执行 npx pagefind --site public --output-subdir pagefind。

5.2 常用选项

① 换索引子目录

效果：索引输出到 public/<name>/，搜索请求路径随之变化。

对应配置：

search:
  pagefind:
    output_subdir: myindex

5.3 全部可调项

• output_subdir：索引子目录（相对 public/），默认 pagefind。
• 构建步骤：hexo generate 之后、部署之前执行 npx pagefind --site public --output-subdir pagefind。
• 加密文章通过 data-pagefind-body 条件渲染自动排除。

5.4 边界与冲突

• 禁用下划线开头的目录名：GitHub Pages（Jekyll）会忽略 _ 开头的目录/文件。
• 只跑 hexo generate 不跑 pagefind，则该引擎无索引、搜索无结果。
• 索引是构建产物，文章更新必须重新扫描。

5.5 小结

• 最小可用：enable: true + 构建后跑一次 pagefind
• 搜不到：确认 public/pagefind/ 存在
• 目录名：别用 _ 开头
• 加密文：自动排除，无需配置

6. 多语言与高亮

用途：多语言站点的结果分组与语言偏好，以及三引擎统一的高亮实现。

学习路径：如何启用 → 常用选项 → 全部可调项 → 边界与冲突

6.1 如何启用

效果：搜索结果显示当前语言版本优先，其他语言结果排在后面；命中词包在 <mark> 中。

对应配置：无独立开关，随 preference 语言段与搜索配置自动生效。

6.2 常用选项

① 语言偏好

效果：结果按读者上次选择的语言排序。

对应配置：

preference:
  default_lang: zh-cn

读者偏好存 localStorage['wiki_lang']，非法值回落到默认语言。

6.3 全部可调项

• 结果过滤：search.js 的 applyLangFilter → groupAndFilter，按路径语言前缀分组。
• 语言偏好：读取 localStorage['wiki_lang']，非法值回落到默认语言。
• 展示优先级：偏好语言 → 默认语言 → 首条。
• 高亮：三引擎共用 SearchEngine._highlight，命中词加 <mark> 并做 HTML 转义（XSS 防护）。

6.4 边界与冲突

• 语言分组按路径前缀判断，翻译页漏写 lang 会被归到默认语言组。
• 高亮统一走 SearchEngine._highlight，改单引擎的高亮样式不会生效。

6.5 小结

• 默认即正确：无需额外配置
• 结果语言乱：查 preference.default_lang 与翻译页 lang
• 高亮样式：改公共 _highlight，不是改单个引擎