这是《Ubuntu上用Hugo搭建私人博客》系列文章的第六篇。前五篇把环境、站点初始化、主题选型、内容组织这些地基活都干完了，这一篇专门聊侧边导航栏。很多人觉得侧边栏就是个装饰，放两个链接完事，实际折腾下来发现里面门道不少：菜单层级怎么设计、高亮状态怎么判断、窄屏下怎么处理、多语言站点怎么办，每一环都有坑。

这篇文章我按实战顺序来写：先讲清楚侧边导航栏在Hugo里的几种实现思路，再给出一套可以直接抄的配置方案，然后是样式定制和响应式处理，最后整理我踩过的那些问题。不管你是照着主题文档配菜单，还是打算自己撸一个侧边栏模板，这篇都能给你省下不少时间。

1. 侧边导航栏到底该放什么内容

1.1 先想清楚导航架构再做配置

很多人搭博客上来就急着写代码，结果菜单改来改去，越改越乱。我建议先花10分钟想清楚一个问题：你的侧边栏要给访问者提供什么？

博客侧边栏通常承担两类职责：一类是站内导航，告诉读者"这个博客里有什么"，比如首页、文章归档、分类、标签、关于页面；另一类是信息聚合，把最近更新、热门文章、订阅入口这些动态内容放在显眼位置。这两类内容混在一起，侧边栏就会显得杂乱。

我的习惯是优先保证导航的清晰度。侧边栏顶部放站点名称和一句简介，下面紧跟主导航菜单，再往下才考虑放标签云、归档列表这类辅助信息。如果你的博客刚起步，内容还不多，侧边栏甚至可以只保留导航和搜索框，留白也是一种设计。

1.2 菜单层级的取舍与Hugo的菜单模型

Hugo的菜单系统相比纯HTML写死的导航有个明显优势：菜单结构可以灵活配置，而且和页面内容解耦。你把菜单定义写在配置文件里，模板里只需要循环输出，之后加菜单项、调顺序都不需要碰HTML。

不过Hugo的菜单模型非常简单，就是扁平化的菜单项加一个可选的父子关系。它没有那种复杂的多级嵌套权限控制，但对付博客导航完全够用。我的建议是菜单层级控制在两层以内：顶层放"首页""文章""分类"这种大项，需要细分的地方比如"文章"下面挂"全部文章""归档年份"，最多两层就行了。超过两层，用户找东西的成本会上升，移动端展示也麻烦。

这里要注意一个概念区别：Hugo的菜单（menu）和内容组织（section/taxonomy）不是一回事。菜单是你主动指定的一组链接，可以指向任意URL；而分类、标签这些是内容本身的属性，Hugo会自动生成对应的列表页。侧边导航栏里的"分类"和"标签"入口，本质上是指向这些自动生成的列表页，但入口顺序、显示名称是你在菜单配置里控制的。

2. 三条实现路线：从躺平到全定制

2.1 路线一：直接用主题自带的侧边栏配置

现在很多Hugo主题都把侧边栏做成了可配置模块。你在配置文件里打开sidebar开关，然后指定要显示哪些区块，比如作者介绍、分类列表、最近文章、标签云，主题会自动渲染。这种方案对不想碰代码的朋友最友好，缺点也很明显：你能配置的只是主题作者预设的选项，想调整区块顺序、改样式细节，往往得去翻主题源码。

2.2 路线二：用Hugo的Menu系统驱动侧边栏

这套方案是我今天重点要讲的。思路是你把菜单项定义在配置或者页面前置参数里，然后写一个sidebar的partial模板，让菜单数据自动生成导航HTML。它的好处是导航内容集中管理，改菜单项不用去翻模板文件；同时借助Hugo模板里的菜单上下文方法，可以比较精确地判断当前页面属于哪个菜单项，从而实现高亮定位。

2.3 路线三：完全手写侧边栏模板

不依赖主题，自己写死整个侧边栏的HTML。这样做自由度最高，想怎么布局就怎么布局，但后续维护成本也最高：每加一个导航链接都要改模板文件，而且很容易出现一个细节忘了同步。我自己平时不推荐这种写法，除非你想练手或者做个高度定制的首页。

把三条路线放一起对比更直观：

我最终选了路线二，核心原因就一条：让数据驱动布局，而不是让布局绑定数据。文章会越来越多，分类会调整，菜单项跟着变，如果每次调整都要去翻HTML，维护负担太重了。

3. 实操：从零配置一套侧边导航栏

3.1 在config里定义菜单项

Hugo的菜单定义可以放在站点配置文件里，也可以放在单个页面的前置参数里。对于侧边栏这种全站统一的导航，放站点配置更合适。以toml格式为例：

# config.toml [menu] [[menu.sidebar]] name = "主页" url = "/" weight = 1 [[menu.sidebar]] name = "文章" url = "/posts/" weight = 2 [[menu.sidebar]] parent = "文章" name = "全部文章" url = "/posts/" weight = 21 [[menu.sidebar]] parent = "文章" name = "分类" url = "/categories/" weight = 22 [[menu.sidebar]] parent = "文章" name = "标签" url = "/tags/" weight = 23 [[menu.sidebar]] name = "关于" url = "/about/" weight = 3

几个关键字段说明一下：

• name：菜单项显示的文字。
• url：链接地址。这里有个容易踩的坑，url写相对路径还是绝对路径，取决于你有没有把博客部署到子路径。如果你的站点将来要跑在类似https://example.com/blog/这种子目录下，url要以baseURL里的子路径开头，或者直接用相对路径。我就遇到过博客部署到子目录后，侧边栏链接全部多了一截目录的情况，后面排查半天才发现是url写法和baseURL配置不匹配。
• weight：排序权重，数值越小越靠前。父子菜单之间，我习惯让子菜单的权重跟在父菜单后面留出余量，比如父菜单是10，子菜单从11开始，这样以后插入新菜单项不用大改。
• parent：父菜单项的identifier或name。这里需要注意，如果父菜单项的name在网站其他地方被改了，子菜单会找不到父级，所以更稳妥的做法是给父菜单项加上identifier字段，然后子菜单的parent指向这个identifier。

3.2 在页面级配置里挂菜单项

除了站点全局菜单，页面前置参数里也可以单独定义菜单项。这个常用于把某个独立页面加入导航。比如关于页面，你可以在它的front matter里写：

--- title: "关于" menu: sidebar: name: "关于我" weight: 3 ---

这样配置的效果和全局配置差不多，区别在于菜单项的归属：页面级菜单跟着内容页面走，如果哪天删了这个页面，菜单项自动消失，不会在配置文件里留下死链。我的习惯是全局菜单管架构、页面级菜单管特殊入口，两者结合用。

不过要注意一个坑：如果同一个菜单名在页面前置参数和站点配置里都定义过，Hugo会合并而不是覆盖，具体行为取决于你的Hugo版本。想精确控制的话，我建议主要用站点配置统一管理侧边栏，页面级菜单只在少数场景用，避免出现两个同名菜单项的尴尬局面。

3.3 编写sidebar模板

有了菜单数据，接下来写模板。在layouts/partials/sidebar.html里放以下内容：

{{ $currentPage := . }} <aside class="sidebar"> <div class="sidebar-header"> <a href="{{ .Site.BaseURL | relURL }}" class="sidebar-title">{{ .Site.Title }}</a> {{ with .Site.Params.description }} <p class="sidebar-desc">{{ . }}</p> {{ end }} </div> <nav class="sidebar-nav"> <ul class="sidebar-menu"> {{ range .Site.Menus.sidebar }} {{ if .HasChildren }} <li class="menu-item menu-item-has-children {{ if $currentPage.HasMenuCurrent "sidebar" . }}active{{ end }}"> <a href="{{ .URL | relURL }}">{{ .Name }}</a> <ul class="sub-menu"> {{ range .Children }} <li class="sub-menu-item {{ if $currentPage.IsMenuCurrent "sidebar" . }}active{{ end }}"> <a href="{{ .URL | relURL }}">{{ .Name }}</a> </li> {{ end }} </ul> </li> {{ else }} <li class="menu-item {{ if $currentPage.IsMenuCurrent "sidebar" . }}active{{ end }}"> <a href="{{ .URL | relURL }}">{{ .Name }}</a> </li> {{ end }} {{ end }} </ul> </nav> {{ if .Site.Params.sidebarSearch }} <div class="sidebar-search"> <form action="{{ "search/" | relURL }}" method="get"> <input type="text" name="q" placeholder="搜索文章…"> </form> </div> {{ end }} </aside>

这段模板里最关键的是两个上下文方法：

• IsMenuCurrent：判断当前页面是否就是某个菜单项指向的页面。比如你在文章归档页，对应菜单项就会被标为高亮。
• HasMenuCurrent：判断当前页面是否在某个菜单项的子树范围内。比如你正在看某篇文章，这篇文章属于"文章"这个大分类下的内容，那么"文章"这个父菜单项会被标为高亮。

这一对方法配合使用，能让导航高亮状态显得很智能：父级、子级、叶子页面都能正确命中对应的菜单项。很多刚开始接触Hugo模板的人会忽略这两个方法，自己用eq .Permalink .URL去判断，结果文章页、分类页、标签页的高亮逻辑写出一堆if else，还容易判断错。能用内置方法解决的，就别自己造轮子。

3.4 把侧边栏挂到页面布局里

模板文件写好之后，要让它出现在页面上。Hugo主题的布局文件一般都有一个基础模板baseof.html，页面内容都嵌入到它里面。你需要在baseof或对应的single/list模板里引用刚才的partial：

<!-- layouts/_default/baseof.html --> <!DOCTYPE html> <html lang="{{ .Site.Language.Lang }}"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>{{ .Title }} | {{ .Site.Title }}</title> {{ block "head" . }}{{ end }} </head> <body> <div class="layout"> {{ partial "sidebar.html" . }} <main class="content"> {{ block "main" . }}{{ end }} </main> </div> </body> </html>

布局结构上我用一个.layout容器包住侧边栏和主内容区，接下来样式部分会让它们左右排布。如果你用的是某个现成主题，不要直接改主题的baseof.html，而是用Hugo的模板覆盖机制：在站点根目录的layouts目录下放同名文件，Hugo会优先使用你放的文件，这样主题升级时你的定制不会被冲掉。

我在这里吃过一次亏：刚接触Hugo时直接改了安装目录下的主题模板，后来主题一更新，我所有改动全部被覆盖，文章里引用的class也全部失效。从那以后我所有定制只放在站点根目录的layouts和assets里，主题本身保持原样。

4. 样式定制与响应式布局

4.1 用Sass组织侧边栏样式

Hugo在资源处理方面做得比较成熟，你可以用assets/scss目录放样式源码，然后在模板里用resources.Get加toCSS处理。下面是一个侧边栏样式的示例：

// assets/scss/sidebar.scss .sidebar { width: 280px; padding: 24px; border-right: 1px solid #e8e8e8; position: sticky; top: 0; height: 100vh; overflow-y: auto; background: #fff; } .sidebar-header { margin-bottom: 24px; } .sidebar-title { font-size: 1.5rem; font-weight: 700; color: #222; text-decoration: none; } .sidebar-desc { margin-top: 8px; font-size: 0.875rem; color: #777; } .sidebar-menu { list-style: none; margin: 0; padding: 0; .menu-item { margin-bottom: 4px; > a { display: block; padding: 8px 12px; border-radius: 6px; color: #444; text-decoration: none; transition: background 0.2s; &:hover { background: #f5f5f5; } } &.active > a { background: #f0f0f0; color: #111; font-weight: 600; } } .sub-menu { list-style: none; margin: 4px 0 4px 16px; padding: 0; .sub-menu-item { a { display: block; padding: 6px 10px; font-size: 0.9rem; color: #666; text-decoration: none; border-radius: 4px; &:hover { background: #fafafa; } } &.active a { color: #333; font-weight: 600; background: #f5f5f5; } } } }

样式上我遵循几个原则：导航项的点击热区要够大，所以用了块级展示加内边距；高亮状态和hover状态要有区分度，hover用浅灰，当前页高亮用深一点的底色加粗字体；子菜单相对父级缩进，视觉上形成层级感。

4.2 响应式处理：窄屏下的侧边栏

侧边栏的响应式处理是实操中最容易翻车的部分。桌面端280px宽的栏很舒服，但手机屏幕上如果硬塞一个280px的固定栏，内容区几乎没地方放。处理思路通常是两种：

一种是侧边栏折叠：窄屏下把侧边栏藏起来，点击菜单按钮后从左侧滑出，遮罩层覆盖内容区。这种方案适合侧边栏内容比较丰富的情况。另一种是侧边栏降级：窄屏下直接把侧边栏挪到主内容下方，变成普通的信息区块。这种方案实现简单，但用户在页面上找导航的路径变长了。

我选了折叠方案，用一小段原生JavaScript控制展开和收起：

<button class="sidebar-toggle" aria-label="切换导航"> <span></span><span></span><span></span> </button>

// assets/js/sidebar.js (function () { const toggle = document.querySelector('.sidebar-toggle'); const sidebar = document.querySelector('.sidebar'); const overlay = document.querySelector('.sidebar-overlay'); if (!toggle || !sidebar) return; toggle.addEventListener('click', function () { sidebar.classList.toggle('open'); if (overlay) overlay.classList.toggle('visible'); document.body.classList.toggle('sidebar-open'); }); })();

在Hugo里挂载JavaScript资源时用resources.Get加js.Build处理，能自动做压缩和bundle。样式方面，断点我选在768px，这也是大多数框架的常见平板竖屏断点：

@media (max-width: 768px) { .layout { position: relative; } .sidebar { position: fixed; left: 0; top: 0; transform: translateX(-100%); transition: transform 0.3s ease; z-index: 100; width: 280px; height: 100vh; } .sidebar.open { transform: translateX(0); } .sidebar-overlay { display: none; position: fixed; inset: 0; background: rgba(0, 0, 0, 0.4); z-index: 99; } .sidebar-overlay.visible { display: block; } .sidebar-toggle { display: inline-flex; flex-direction: column; gap: 4px; padding: 10px; span { display: block; width: 22px; height: 2px; background: #333; } } }

这里有个细节：桌面端按钮默认隐藏，只有窄屏下才显示，所以要在媒体查询里把display从none改成inline-flex。如果忘了写桌面端初始状态，按钮会在宽屏上露出来，很影响观感。

5. 常见问题与排查记录

5.1 菜单不显示的几类原因

症状是侧边栏模板引用了.Site.Menus.sidebar，但页面渲染出来菜单区域是空的。遇到这种情况，第一反应不是去查模板，而是先在命令行跑一下hugo，看构建过程有没有报提示。如果构建正常但菜单还是空的，最可能的原因就是配置格式不对。

特别注意配置文件里[menu]的层级关系。toml格式下，每个菜单项是[[menu.sidebar]]，方括号必须是两层；写成[menu.sidebar]的话，后面的键值会被解析成menu.sidebar这个单一值，后面再写一项就会覆盖前面的。这个问题在Hugo新手里出现频率极高，往往检查几遍都看不出来。

5.2 高亮状态不生效

模板里用了IsMenuCurrent和HasMenuCurrent，但当前页面并没有高亮。大部分原因是菜单项的url和页面实际生成的路径不一致。

比如文章列表页长这样：https://example.com/posts/，你的菜单url写成了/posts，少了结尾斜杠，Hugo在做字符串比较时不认为它们相等。另外Hugo有给URL做relURL处理的逻辑，如果你在模板里对.URL做了额外包装，也可能破坏比较结果。

判断这类问题最有效的方法，是右键页面选择查看源文件，看看生成的HTML里菜单项的href值，再对照浏览器地址栏的URL。两边不一致，问题基本出在url写法上；两边一致但还是不高亮，才需要考虑模板逻辑。

5.3 子菜单层级显示异常

子菜单项没挂在父菜单下面，全部平铺在侧边栏里。排查思路是看配置里父菜单项的identifier和子菜单的parent是否对得上。注意Hugo有个隐蔽行为：如果父菜单项没有显式写identifier，这个值默认等于name。子菜单的parent写的是父级name的时候，正常情况能匹配上；但中文场景下，name里有空格、全半角符号差异，就很容易失配。使用identifier是更稳妥的做法。

5.4 常见问题速查

5.5 调试侧边栏的几个实用命令

排查菜单问题，我常常开两个终端。一个跑hugo server，另一个用来查配置：

# 查看当前站点激活的所有菜单定义 hugo config menus # 检测配置与资源问题，带verbose输出 hugo --verbose --debug # 查看渲染后的HTML中菜单部分，快速确认url hugo server

hugo config menus这个命令很多人不知道，它在调试菜单场景下特别好用，直接输出当前所有菜单的键值结构。输出结构里看到sidebar菜单不存在，那就是配置没被正确加载；看到菜单项存在但url值异常，那就是你的url写法有问题。

6. 还有一个被忽略的细节：多语言站点的菜单处理

如果你的博客以后要开双语甚至多语言，侧边栏菜单的name字段会变成一个麻烦。Hugo内置了i18n机制，菜单项的name字段支持从语言包取翻译值。写法是name = "menu.about"这种形式，Hugo会用它作为i18n的key去查询翻译，查不到时才把原字符串原样显示。

这个机制虽然好用，但有个陷阱：一旦菜单项name是这种带点号的"伪翻译key"，parent字段的匹配也会按翻译key而不是显示文本来算。也就是说，子菜单的parent要填"menu.articles"而不是"文章"。所以从一开始我就强调用identifier管理父子关系，不仅是为了防止名字改动导致失配，也是为多语言留的后路。

如果你只有单一语言，i18n这个特性可以先不管，但建议从第一天起就养成写identifier的习惯。等真到了要多语言的那天，你会发现改起来只是一行配置的事。

7. 侧边栏之外：别忘了页面内导航

侧边导航栏解决的是"从任何页面快速跳转到站内主要区域"的问题，但它替代不了文章页内部的目录导航。如果你写的文章很长，侧边栏里最好再放一个"本页目录"区块，把文章内的小标题链接进去。Hugo里可以通过.TableOfContents变量直接输出目录，配合CSS渲染成树形结构。

我的做法是侧边栏分为上下两段：上段是全站导航菜单，下段是当前文章的目录。全站导航无论在哪一页都是固定的，目录区域只在文章页显示。这样读者的视线不必来回切换，侧边栏的信息承载效率也更高。具体实现上，目录区用{{ if .TableOfContents }}{{ .TableOfContents }}{{ end }}判断是否存在目录，有则输出，没有就不渲染。

不过这里要注意性能和缓存问题：如果侧边栏里渲染了文章目录，那么每个页面的侧边栏内容都不一样，构建缓存时就不能把partial输出整个缓存下来。站点文章多了以后，这个影响不算大，但我见过有人为了节省构建时间把侧边栏全部缓存，结果目录一直显示上一篇文章的。省那几秒构建时间，不值得。

侧边导航栏做到这个程度，已经能满足大多数博客的日常使用了。从配置菜单、编写模板、定制样式、处理响应式到排查问题，几个环节都走通之后，你会对Hugo模板化的内容组织方式有更深的理解。后面如果想让侧边栏更智能化，可以考虑按section自动生成菜单项，或者结合阅读数据和标签热度动态调整展示内容，这些都是在现有骨架上的扩展，核心思路不会变。