hugo 项目中 markdown 内容未显示，通常由缓存残留、路径配置错误或模板调用不当导致；本文聚焦最易忽略却高频发生的缓存问题，并提供系统性排查步骤。
hugo 项目中 markdown 内容未显示，通常由缓存残留、路径配置错误或模板调用不当导致；本文聚焦最易忽略却高频发生的缓存问题，并提供系统性排查步骤。
当你首次使用 Hugo 构建多语言站点（如 german/home/company.md），却在浏览器和生成的 public/index.html 中完全看不到 .Content 渲染结果时，请优先执行缓存清理——这是该问题最常见且最易被忽视的根本原因。
Hugo 自 v0.110+ 起默认启用模块缓存（module cache）与文件系统缓存（FS cache），尤其在启用 i18n、自定义目录结构或频繁修改内容路径后，缓存可能滞留旧的页面树快照，导致 site.GetPage 查找不到目标页，.Content 返回空值，而控制台无任何报错。
✅ 立即生效的解决方案：
# 彻底清除 Hugo 缓存（推荐） hugo --cleanDestinationDir # 或更彻底地清空所有缓存（含 module cache） hugo clean --confirm # 开发时建议始终启用 --ignoreCache 避免干扰 hugo server --ignoreCache --disableFastRender
⚠️ 注意事项：
-
--cleanDestinationDir会清空public/目录并重建，确保输出干净； -
hugo clean是 Hugo 0.115+ 引入的专用命令，比手动删除.hugo_cache/更可靠； - 即使你确认路径（如
"german/home/company"）符合 Hugo 页面路径规则（即content/german/home/company/_index.md或company.md对应section页面），仍需排除缓存干扰——因为缓存可能导致 Hugo 根本未将该文件纳入页面树（.Site.Pages中不可见）； - 若使用
hugo server，务必重启服务（而非仅刷新浏览器），因开发服务器会缓存解析结果。
? 进阶验证技巧（排除其他潜在原因）：
<!-- 在 home/list.html 中临时添加调试输出 -->
{{ printf "DEBUG: Current page = %s" .RelPermalink | safeHTML }}
{{ printf "DEBUG: company page found = %v" (isset .Site.GetPage "german/home/company" "Content") | safeHTML }}
{{ with $.Site.GetPage "german/home/company" }}
{{ printf "DEBUG: company.Content length = %d" (len .Content) | safeHTML }}
{{ else }}
{{ printf "DEBUG: company page NOT FOUND!" | safeHTML }}
{{ end }}总结：Hugo 的“内容不渲染”90% 以上并非模板语法或路径错误，而是缓存机制导致的页面索引失效。养成 hugo clean --confirm 后再构建的习惯，能节省大量调试时间。完成清理后，重新运行 hugo server，你的 company.md 和 _index.md 内容将立即正常渲染。
