Hugo中图片渲染异常问题求助

环境与问题重现 #

我的Hugo静态网站文件夹结构如下：

content
└── en
    └── docs
        ├── software-practices
        │   ├── _index.md
        │   └── Git
        │       ├── _index.md
        │       └── branching
        │           ├── _index.md
        │           └── images
        │               └── git-branching.png
        └── ...

在content/en/docs/software-practices/Git/branching/_index.md中使用了以下图片引用：

![Branching Diagram](images/git-branching.png)

问题现象：

• 首次执行hugo server启动服务器时，图片无法渲染，仅显示替代文本
• 将_index.md重命名为其他名称（如myfile.md），图片立刻正常渲染；改回_index.md后也能显示
• 重启hugo server后，问题再次出现

原因分析 #

这一问题核心在于Hugo对**章节首页（_index.md）**的资源处理逻辑差异：

1. Hugo启动时的预构建阶段，会将_index.md识别为section（章节）节点，其相对路径的资源解析规则与普通页面（非_index.md文件）不同，首次构建时可能出现路径映射偏差
2. 重命名文件会触发Hugo的热重载机制，此时Hugo会重新扫描该文件的关联资源，自动修正路径映射；但重启服务器后，预构建阶段的路径解析问题会再次出现

解决方案 #

方案1：改用绝对路径引用图片 #

直接使用基于站点根目录的绝对路径，规避相对路径在章节节点下的解析问题：

![Branching Diagram](/en/docs/software-practices/Git/branching/images/git-branching.png)

方案2：使用Hugo内置资源短代码（推荐） #

借助Hugo的figure短代码或资源获取函数，让框架自动管理资源路径：

{{< figure src="images/git-branching.png" alt="Branching Diagram" >}}

如果需要对图片进行裁剪、压缩等处理，可使用资源获取方式：

{{ $image := resources.Get "en/docs/software-practices/Git/branching/images/git-branching.png" }}
![Branching Diagram]({{ $image.RelPermalink }})

方案3：启动时清除缓存 #

每次启动服务器前，强制清除Hugo缓存，避免缓存导致的路径异常：

hugo server --cleanDestinationDir --ignoreCache

内容的提问来源于stack exchange，提问作者0xREDACTED