Hugo首页渲染最新博文时figure短代码图片路径失效问题

问题原因 #

Hugo 对Markdown和短代码里的相对路径，默认基于当前正在渲染的页面路径解析，而非Markdown源文件所在目录。

• 博客详情页渲染时，当前路径是对应博文的地址，./image.png会被解析为[博文地址]/image.png，和图片实际存放路径匹配，所以能正常加载
• 首页渲染时，当前路径是站点根路径，./image.png会被解析为[站点根地址]/image.png，自然找不到存放在博文目录下的资源，导致图片加载失败

最优解决方法（无需修改现有文章的短代码写法） #

直接修改主题下的figure短代码模板，让它自动识别相对路径，拼接对应博文的永久链接前缀，不管在哪个页面渲染都能生成正确的资源地址。

1. 打开主题目录下的layouts/shortcodes/figure.html文件，如果该文件不存在就新建一个
2. 把src属性的处理逻辑替换为自动拼接路径的版本，参考代码如下：

{{- $src := .Get "src" -}}
{{- /* 仅对非根路径、非外链的相对路径做拼接处理 */ -}}
{{- if not (or (hasPrefix $src "/") (hasPrefix $src "http") (hasPrefix $src "https")) -}}
  {{- $src = printf "%s%s" .Page.Permalink (strings.TrimPrefix "./" $src) -}}
{{- end -}}
<figure>
  <img loading="lazy" src="{{ $src | safeURL }}" alt="{{ .Get "caption" | default "" }}">
  {{ with .Get "caption" }}<figcaption>{{ . }}</figcaption>{{ end }}
</figure>

修改完成后，你原来写的{{< figure src="./image.png" caption="Imagem caption" >}}不需要做任何改动：

• 在详情页渲染时，.Page指向当前博文，拼接后路径和原来一致，正常加载
• 在首页、分类页、标签页等任何列表页渲染博文摘要/内容时，.Page依然指向图片所属的博文，会自动生成[博文永久链接]/image.png的正确路径，不会再出现解析错误。

临时适配方法（不想改短代码时用） #

如果你不想修改短代码模板，可以在写figure短代码时手动调用Page的Permalink变量拼接路径，写法如下：

{{< figure src="{{ .Page.Permalink }}image.png" caption="Imagem caption" >}}

注意：该方法要求你使用Hugo的Page Bundle结构组织内容，也就是每篇博文单独建文件夹，博文的index.md和对应图片放在同一个文件夹下，否则路径匹配会出错。

额外配置建议 #

如果你的站点需要部署在子路径下，建议在站点配置文件config.toml/config.yaml中开启relativeURLs = true，配合上述短代码修改，所有环境下路径都能正常解析。

内容的提问来源于stack exchange，提问作者Leonardo Ratzlaff