本文详解如何在 Hugo 静态站点生成器中，针对不同 URL 路径（如 /blog-folder-1/ 与 /blog-folder-2/）差异化渲染列表页，避免默认 list.html 混淆内容，并通过 Section 分离、模板优先级和 where 过滤实现精准控制。
本文详解如何在 hugo 静态站点生成器中，针对不同 url 路径（如 `/blog-folder-1/` 与 `/blog-folder-2/`）差异化渲染列表页，避免默认 `list.html` 混淆内容，并通过 section 分离、模板优先级和 `where` 过滤实现精准控制。
Hugo 的模板渲染遵循明确的层级查找规则：当访问 example.com/blog-folder-1/ 时，Hugo 会优先尝试匹配 layouts/blog-folder-1/list.html；若不存在，则回退至 layouts/_default/list.html。因此，解决“同一 list.html 错误展示跨目录文章”的核心思路是：利用 Section 模板隔离 + 条件过滤双重保障。
✅ 方案一：为每个 Section 定义专属模板（推荐）
在主题 layouts/ 目录下创建与内容目录同名的子目录，放入定制化模板：
layouts/
├── _default/
│ └── list.html # 通用兜底（如首页）
├── blog-folder-1/
│ └── list.html # 仅渲染 blog-folder-1 下的文章
└── blog-folder-2/
└── list.html # 仅渲染 blog-folder-2 下的文章此时 blog-folder-1/list.html 可直接使用 .Pages（无需过滤），因为 Hugo 已自动限定作用域为该 Section 内所有页面：
{{ define "main" }}
<h1>{{ .Title }}</h1>
<ul>
{{ range .Pages.ByPublishDate.Reverse }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}? 提示：Hugo 自动将
content/blog-folder-1/视为 Section，其.Section值即"blog-folder-1"，无需手动配置。
✅ 方案二：在通用 list.html 中动态过滤（灵活但需谨慎）
若坚持复用 _default/list.html，可在循环中显式排除非目标 Section 的页面。例如，在 blog-folder-1/ 页面中只显示本 Section 文章：
{{ $currentSection := .Section }}
{{ range $i, $p := (where .Site.RegularPages "Section" "==" $currentSection).ByPublishDate.Reverse }}
<article>
<h2><a href="{{ $p.RelPermalink }}">{{ $p.Title }}</a></h2>
<time>{{ $p.Date.Format "2006-01-02" }}</time>
</article>
{{ end }}⚠️ 注意事项：
- 使用
.Site.RegularPages（而非.Data.Pages）确保获取全站常规页面，再通过where筛选； -
.Section在 Section 列表页（如/blog-folder-1/）中返回"blog-folder-1"，但在首页（/）中为空字符串，需额外判断； - 若需分页，应结合
(.Paginate (where ...))，如答案所示：{{ range $i, $p := (.Paginate (where .Site.RegularPages "Section" "==" .Section)).Pages }}
? 补充：避免常见陷阱
-
拼写一致性：确保文件夹名（
blog-folder-1）、URL 路径（/blog-folder-1/）与模板目录名（layouts/blog-folder-1/）完全一致（含连字符）； -
首页特殊处理：首页无 Section，建议单独用
layouts/_default/list.html+where .Params.displayHomepage "true"逻辑，与 Section 列表页解耦； -
调试技巧：在模板中临时添加
{{ printf "%#v" .Section }}或{{ .CurrentSection.Title }}查看当前上下文值。
通过 Section 模板隔离，你不仅能彻底规避跨目录内容污染，还能为不同栏目定制独立样式、分页逻辑甚至 SEO 元数据——这才是 Hugo “约定优于配置”设计哲学的最佳实践。
