Hugo LoveIt 主题图片圆角终极解决方案：从踩坑到完全生效

一篇写给新手的手把手实战教程

2026-03-14 约 3088 字预计阅读 7 分钟次阅读

/2026/03/14/hugo-loveit-image-rounded-corners/featured-image.webp

一、先说结论：最后真正生效的方法是什么？

如果你和我一样，使用的是 Hugo + LoveIt 主题，并且文章中的图片是通过 image shortcode 插入的，那么最稳妥的做法不是给每一张图单独写 style，也不是依赖 class="rounded-img"，而是直接在全站的 _custom.scss 中给实际渲染出来的图片类名添加圆角样式。

最终可用的 CSS 如下：

// ==============================
// Custom style
// 自定义样式
// ==============================

img.lazyloaded {
  border-radius: 8px !important;
}

然后文章里直接这样写图片即可：

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" src_s="/images/post-end/night-rain-lamp-800.webp" src_l="/images/post-end/night-rain-lamp-1600.webp" width="100%" >}}

这样写之后，图片会保持 LoveIt 原本的懒加载和画廊能力，同时自动带上圆角效果。

二、我一开始是怎么踩坑的？

一开始我的思路很自然：既然 LoveIt 的 image shortcode 支持 class 参数，那我就给图片加一个类，再在 CSS 里写：

.rounded-img img {
  border-radius: 8px;
}

文章中这样写：

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%"
          class="rounded-img" >}}

看起来逻辑完全正确，但结果却是：一点效果都没有。

后来排查才发现，问题不在 CSS 语法本身，而在于 LoveIt 实际渲染出来的 HTML 结构，和我一开始以为的不完全一样。也就是说，你写进 shortcode 的 class="rounded-img"，未必会按你期待的方式出现在最终页面里。

三、`style` shortcode 为什么也没救场？

后来我又试过 LoveIt 的 style shortcode，想在文章局部直接包裹一段样式，比如这样：

{{< style ".rounded-img img { border-radius: 8px; }" >}}
{{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%"
          class="rounded-img" >}}
{{< /style >}}

这一步有两个问题：

1. 如果闭合标签没写对，会直接报错

比如：

shortcode "style" must be closed or self-closed

这说明 style shortcode 不是随便写一行就行，它必须严格成对出现。

2. 就算不报错，也不一定生效

原因很简单：如果目标元素根本没有你预期中的 rounded-img 类，那你写再多 .rounded-img img 也匹配不到任何元素。

所以这一条路，理论上可行，实战里却很容易掉坑。

四、真正的问题出在哪？

真正的突破点，是我打开浏览器开发者工具，看到了图片的实际 HTML。

图片最终渲染出来更接近这种结构：

<img class="lazyautosizes lazyloaded"
     src="/images/post-end/night-rain-lamp-1200.webp"
     data-src="/images/post-end/night-rain-lamp-1200.webp"
     data-srcset="/images/post-end/night-rain-lamp-800.webp, /images/post-end/night-rain-lamp-1200.webp 1.5x, /images/post-end/night-rain-lamp-1600.webp 2x"
     data-sizes="auto"
     alt="文尾配图水墨画图片"
     width="100%">

这时候就明白了：

真正稳定存在的类名，不是我手写的 rounded-img
而是 LoveIt 配合懒加载库自动加上的 lazyloaded
所以最稳妥的选择器，不应该写成 .rounded-img img
而应该直接命中真实渲染出来的 <img> 元素

也正因为这样，下面这段 CSS 最后才真正生效：

img.lazyloaded {
  border-radius: 8px !important;
}

五、正确操作步骤，照着做就行

第一步：确认 `_custom.scss` 文件位置正确

文件必须放在项目根目录下：

assets/css/_custom.scss

注意几点：

文件名必须是 _custom.scss
前面这个下划线不能少
目录必须是项目根目录下的 assets/css/
不是 themes/LoveIt/assets/css/
也不是 custom.scss、custom-2.scss 这种名字

第二步：在 `_custom.scss` 中写入最终生效代码

// ==============================
// Custom style
// 自定义样式
// ==============================

img.lazyloaded {
  border-radius: 8px !important;
}

如果你只想让文章正文中的图片有圆角，不想让别的图片也一起变圆角，可以再缩小作用范围，比如：

.single img.lazyloaded {
  border-radius: 8px !important;
}

不过如果你现在的目标就是“全站图片统一圆角”，那直接用第一版就够了。

第三步：文章里继续正常使用 `image shortcode`

现在文章中可以直接这样写：

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%" >}}

如果你不需要画廊模式，也可以只写最简版：

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          width="100%" >}}

这两种写法都不会影响圆角效果，因为圆角现在已经由全局 CSS 接管了。

** 如果你在本地预览，继续操作下面的第四步。 **

第四步：删除缓存并重启 Hugo

这是很多人最容易忽略的一步。

修改完 SCSS 后，建议直接删除这两个目录：

resources/
public/

然后重新运行：

hugo server

最后在浏览器里执行强制刷新：

Ctrl + Shift + R

如果你不清缓存，浏览器或者 Hugo 可能还在继续使用旧的 CSS 文件，你会误以为“怎么还是没效果”。

六、`hugo.toml` 里到底要不要加配置？

我一开始也怀疑是不是要在 [params.page.library.css] 里加东西，后来证明：不需要。

也就是说，下面这种思路不是这次问题的正确解法：

[params.page.library.css]
  custom = "css/custom.css"

对于 LoveIt 来说，_custom.scss 本身就是主题默认识别的自定义样式入口。只要路径和文件名正确，主题就会自动加载，不需要你再去 hugo.toml 里额外注册。

真正应该关注的，是文章页是否启用了图片画廊能力。我的配置是：

[params.page]
  lightgallery = true

文章 front matter 里也可以这样写：

lightgallery: true

如果你本来就要使用 image shortcode 的画廊能力，这个配置建议开启。

七、`image shortcode` 里几个最容易搞错的参数

1. `alt` 不是可有可无

alt 是替代文本，不只是“图片加载失败时显示一下文字”那么简单。它同时影响：

图片加载失败时的降级显示
屏幕阅读器对图片内容的朗读
搜索引擎对图片内容的理解

所以不要偷懒写成空的，最好写成有意义的描述，比如：

alt="文尾配图水墨画图片"

2. `caption=""` 最好别乱留空

像这样：

caption=""

虽然通常不会报错，但很可能会生成空的说明区域，属于无意义代码。既然不用，就直接省略。

3. `height="auto"` 不建议写

很多人会下意识写：

height="auto"

但这其实不是最合适的用法。更稳妥的方式是：

只写 width="100%"
不写 height
让浏览器按原图比例自动计算高度

4. `src_s` 和 `src_l` 是给画廊准备的

如果你写了：

src_s="/images/post-end/night-rain-lamp-800.webp"
src_l="/images/post-end/night-rain-lamp-1600.webp"

它们主要是服务于 LoveIt 的画廊体验：

src_s：缩略图
src_l：高清图

而页面初始加载时，通常还是以 src 为主。

所以如果你只是想显示一张普通图片，不一定非要把三个尺寸都配齐。

八、我建议的图片写法

场景一：只想简单显示一张图

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          width="100%" >}}

适合文章内普通配图。

场景二：既要显示图片，又要支持画廊查看大图

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%" >}}

适合文末配图、插画、大图展示。

场景三：完全自己控制样式和响应式

如果你不想依赖 shortcode，也可以直接写原生 HTML：

<img src="/images/post-end/night-rain-lamp-1200.webp"
     srcset="/images/post-end/night-rain-lamp-800.webp 800w,
             /images/post-end/night-rain-lamp-1200.webp 1200w,
             /images/post-end/night-rain-lamp-1600.webp 1600w"
     sizes="(max-width: 600px) 800px, (max-width: 1200px) 1200px, 1600px"
     alt="文尾配图水墨画图片"
     loading="lazy"
     style="width:100%; height:auto; border-radius:8px;">

这种方式控制力最强，但维护成本也更高。

九、为什么我最后选择全局圆角？

因为它最省心。

只要你确定自己的网站整体视觉风格就想要圆角图片，那么统一在 _custom.scss 中处理，会比每张图片都手写样式轻松太多。

它的好处有三个：

新文章不用重复写样式
旧文章自动获得统一视觉效果
image shortcode、部分懒加载图片都能一起受益

如果以后你又想改成 12px、6px，甚至改成直角，只需要改一处 CSS 即可。

十、最终可直接照抄的完整方案

`_custom.scss`

// ==============================
// Custom style
// 自定义样式
// ==============================

img.lazyloaded {
  border-radius: 8px !important;
}

文章里的图片写法

{没这字{< image src="/images/post-end/night-rain-lamp-1200.webp"
          alt="文尾配图水墨画图片"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%" >}}

修改后操作顺序

保存 _custom.scss
删除 resources/
删除 public/
重新运行 hugo server
浏览器 Ctrl + Shift + R 强制刷新

十一、这次踩坑给我的提醒

做 Hugo 主题定制时，不要只看文档参数名，更要看最终渲染出来的 HTML。

很多时候你以为问题出在：

toml 没配置
shortcode 没写对
CSS 没生效

但真正的问题其实是：你写的选择器，根本没有命中真实元素。

所以遇到“明明写对了却没效果”的情况，最快的方法不是继续猜，而是：

打开浏览器 F12
在要查看的图片上鼠标右键“检查”
找到实际渲染的 HTML
看类名到底是什么
再写 CSS

这一步，往往比你盲改十次配置都更有效。

如果你也在折腾 Hugo 的 LoveIt 主题，希望这篇文章能帮你少走一点弯路。至少在“给图片加圆角”这件事上，你现在可以一次搞定，不用再来回踩坑了。

–全文完–

“同频之人，终会相遇；同行之路，终有光亮。”

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：

微信公众号：

私人微信号(有验证)：oklife_1314

我的邮箱📫：hero@oklife.me

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自https://oklife.me。