Hugo 博客添加搜索功能踩坑记

背景#

博客搭好之后，发现导航栏里的 Search 链接点进去是 404。分类页面（Categories）偶尔也打不开。排查了一下，记录一下解决过程。

PaperMod 主题虽然有搜索功能，但 Hugo 不会自动生成 /search/ 页面。搜索框的 HTML 模板在主题里有（layouts/_default/search.html），但缺少对应的 content 文件，Hugo 不知道要渲染这个页面。

解决方法： 创建 content/search/_index.md：

1
---
2
title: "Search"
3
layout: "search"
4
---

Hugo 会根据这个文件找到 search.html 模板，生成 /search/index.html。

分类页面本地构建正常，但 GitHub Pages 上线后 404。

原因：GitHub Pages 的 CDN 缓存还没刷新。文件其实已经部署上去了，只是边缘节点还在用旧缓存。

解决方法： 等几分钟缓存过期就好。如果长期不刷新，可以在仓库 Settings → Pages 里点一次 “Re-run deployment”。

搜索页面有了，但输入关键词没反应。

检查发现搜索功能依赖 Fuse.js（前端模糊搜索库），通过 CDN 加载。如果 CDN 被墙或者加载失败，搜索就挂了。

备选方案： 把 Fuse.js 下载到本地 static/js/ 目录，修改模板引用本地文件：

1
<script src="{{ "js/fuse.min.js" | relURL }}"></script>

页面类型	需要做什么
文章列表	自动生成，不需要额外配置
文章详情	`content/posts/xxx.md` 自动生成
分类页面	`content/categories/xxx/_index.md` + frontmatter 里声明 `categories`
标签页面	frontmatter 里声明 `tags`，自动生成
自定义页面（如搜索）	`content/xxx/_index.md` + `layouts/_default/xxx.html`

Hugo 的页面生成是内容驱动的——有 content 文件才有页面，有模板才能渲染。模板和内容缺一不可。