PrimeEdge 主题教程

搜索功能

配置站内搜索

搜索功能 #

PrimeEdge 集成基于 Fuse.js 的客户端搜索。Hugo 构建时生成 /search.json，并通过 Hugo Pipes 将 assets/js/search.js 合并到带内容指纹的站点脚本中，浏览器在前端完成搜索，不需要后端服务。

搜索特点 #

  • 客户端搜索：基于 Fuse.js，无需服务器。
  • 即时结果：输入后 200ms 防抖搜索。
  • 模糊匹配：支持标题和正文摘要匹配。
  • 多内容类型：索引文章、笔记、文档、好物和投资笔记。
  • 弹窗体验：导航栏搜索按钮打开搜索弹窗，ESC 可关闭。

启用搜索 #

当前主题已经包含搜索弹窗、Fuse.js 引入、搜索脚本和搜索索引模板。只需确认配置中包含 Search 输出格式。

[outputs]
  home = ["HTML", "RSS", "Search", "FullRSS", "Feed"]
  page = ["HTML"]
  section = ["HTML", "RSS"]

[outputFormats]
  [outputFormats.Search]
    mediaType = "application/json"
    baseName = "search"
    isPlainText = true

构建后会生成：

/search.json

主题的 layouts/_default/search.json 会索引以下内容类型：

posts, notes, docs, good-things, investing

每条索引包含 title、content、url、type、date。其中 content 是正文纯文本截断后的摘要。

前端加载流程 #

主题页面底部会加载压缩并带内容指纹的站点脚本，搜索库和 search.json 会在用户打开搜索时按需加载：

<script src="/js/site.[内容指纹].js" defer></script>

同时会设置：

window.SEARCH_DATA_URL = "/search.json";
window.FUSE_JS_URL = "/vendor/fuse/fuse.min.js";

如果站点部署在子路径，可以用 relURL 保证 search.json 路径正确。

搜索行为 #

当前 assets/js/search.js 的 Fuse 配置为：

fuse = new Fuse(window.SEARCH_DATA, {
  keys: ['title', 'content'],
  threshold: 0.4,
  includeScore: true,
  includeMatches: true
});
配置说明
keys搜索标题和正文摘要
threshold匹配阈值，越小越严格
includeScore返回匹配分数
includeMatches返回匹配片段，用于高亮

搜索至少输入 2 个字符才会触发。结果会显示内容类型、日期、标题和命中的正文片段。

调整索引范围 #

如需修改可搜索内容类型，编辑主题中的 layouts/_default/search.json：

{{ $pages := where .Site.RegularPages "Type" "in" (slice "posts" "notes" "docs" "good-things" "investing") }}

例如只搜索文章和文档：

{{ $pages := where .Site.RegularPages "Type" "in" (slice "posts" "docs") }}

调整搜索权重 #

如果希望标题权重更高，可以把 keys 改成加权写法：

fuse = new Fuse(window.SEARCH_DATA, {
  keys: [
    { name: 'title', weight: 0.8 },
    { name: 'content', weight: 0.4 }
  ],
  threshold: 0.35,
  includeScore: true,
  includeMatches: true
});

修改脚本后重新部署博客即可生效。

故障排查 #

搜索无结果

  1. 访问 /search.json，确认文件存在且不是空数组。
  2. 检查 [outputs].home 是否包含 Search，不是旧写法 JSON。
  3. 检查浏览器控制台是否加载了 Fuse.js 和 /js/site.[内容指纹].js。
  4. 确认输入至少 2 个字符。

搜索弹窗打不开

检查页面中是否存在 .search-toggle-btn 按钮，以及 layouts/_default/baseof.html 是否包含搜索弹窗结构。

中文搜索不准确

Fuse.js 对中文分词能力有限，可以适当调高 threshold，或减少正文截断长度让结果更聚焦。需要更强中文分词时，可考虑额外接入 Pagefind。

下一步 #

评论

0%