手把手教程：让 Hugo LoveIt 主题文章图片自适应宽度 + 点击放大高清图

有些技术问题，表面上只是一个参数没写对，背后却可能藏着半天、一天，甚至更久的绕路和怀疑。这个问题就是这样：我原本只是想让 Hugo + LoveIt 主题里的文章图片，既能自动适应正文宽度，又能保留点击放大查看高清图的能力，结果前前后后折腾了十几个小时，才把这件事真正理顺。

写下这篇文章，不只是为了记录一个技术解法，更是想把那些我已经踩过的坑、绕过的弯、反复试错后的结论，整理成一条对后来者更平坦一点的路。如果你此刻也正卡在这里，希望这篇文章能帮你省下时间，也省下一点焦躁。

一、我们到底想实现什么效果？

先把目标说清楚，否则很容易一边改配置，一边越改越乱。

如果你和我一样，想做的是博客文章里的普通配图，那大概率你真正需要的是下面这四件事：

• 图片能随着正文内容区宽度自动缩放，在手机和电脑上都不溢出。
• 图片保持原始比例，不被拉伸，也不被压扁。
• 点击图片以后，能够弹出更高清的大图查看。
• 写法尽量简单，不去魔改主题底层模板。

看起来像一个需求，其实是两层逻辑：页面里怎么显示，以及点击后怎么查看大图。很多人之所以被绕进去，就是把这两件事混在了一起。

二、先说结论：最稳妥的方案是什么？

如果你只想快速做对，那就直接用 LoveIt 原生的 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="夜雨孤灯水墨画配图"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%" >}}

配合 lightgallery = true，这就足够让图片在正文里宽度自适应，同时保留点击后查看高清图的体验。

三、第一步：先确认画廊功能已经开启

很多问题不是 shortcode 本身错了，而是画廊能力根本没打开。

打开你的 hugo.toml，在 [params.page] 里确认这一项存在：

[params.page]
  lightgallery = true

如果没有，就手动加上。如果你在本地预览，保存后建议重启一次 hugo server，不要偷懒。很多时候，明明文件已经改了，页面却还是旧效果，问题未必出在代码本身，而是在缓存和重启这一步上。

四、第二步：准备图片，不要一张图走天下

如果你希望图片体验更自然，最好不要只准备一张超大图直接塞进文章里。

更推荐的方式，是为同一张图准备三个尺寸版本，例如：

• night-rain-lamp-800.webp
• night-rain-lamp-1200.webp
• night-rain-lamp-1600.webp

这样做有两个好处。第一，命名规范清晰，后期维护不乱。第二，无论你是用 LoveIt shortcode，还是后面想升级成更细的响应式方案，文件都已经准备好了。

我自己的建议是：图片文件名尽量统一使用小写英文 + 连字符 + 尺寸后缀。技术上中文文件名不一定完全不能用，但在路径、转码、维护和 SEO 上，英文命名通常更稳。

五、第三步：为什么只写 width="100%"，而不写 height="auto"？

这是这类问题里最容易掉进去的坑之一。

很多人看到 HTML 或 CSS 的常见写法，会很自然地写出：

width="100%"
height="auto"

但在 LoveIt 的 image shortcode 这里，height 对应的是 HTML 属性，不是 CSS 那种 height:auto; 的语义。也就是说，你写了 height="auto"，大概率不会得到你想象中的效果，浏览器往往会直接忽略它。

真正稳妥的方式反而更简单：

• 写 width="100%"
• 不写 height
• 让浏览器根据图片原始比例自动计算高度

这才是让图片既适应正文宽度、又不变形的关键。

六、第四步：理解 src、src_s、src_l 的分工

这一点如果不想明白，后面就很容易越用越乱。

在 LoveIt 的 image shortcode 里：

• src 是页面初次显示的默认图片。
• src_s 更偏向画廊中的缩略图用途。
• src_l 则是点击后查看的高清大图。

也就是说，src_s 和 src_l 的重点在于画廊阶段，而不是页面初次加载阶段。

这一点特别重要。因为很多人会误以为只要把 src_s 写成 800px，把 src_l 写成 1600px，浏览器就会自动在手机加载小图、电脑加载大图。其实不是这样的。页面首次显示时，真正起主要作用的还是 src。

所以，如果你现在的目标只是“图片别超出正文、点击还能放大”，那 LoveIt 原生 shortcode 已经足够。如果你想进一步追求真正的响应式加载，那就要进入下一步。

七、如果你想更进一步：真正的响应式加载怎么做？

详细的可用看我写的这篇文档：

图片相关设置

所谓真正的响应式加载，不只是图片视觉上缩小或放大，而是浏览器根据设备宽度和网络状况，主动去选更合适的图片文件。

比如：

• 手机加载 800px
• 平板加载 1200px
• 桌面端加载 1600px

要做到这一点，更适合直接写原生 HTML：

<a href="/images/post-end/night-rain-lamp-1600.webp" class="lightgallery">
    <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;">
</a>

这段代码真正解决的是“加载哪一张图”这个问题。

• srcset 告诉浏览器：我这里有多张不同宽度的图。
• sizes 告诉浏览器：在不同屏幕宽度下，这张图大概会占多宽。
• 浏览器再根据自己的判断，挑出最合适的资源来加载。

如果你对性能比较敏感，或者文章图片特别多，这种方式会比单纯 shortcode 更细致，也更像一个认真打磨过的站点该有的样子。

八、几个最常见的问题，我替你先问了

1. 为什么我加了 width="100%"，图片还是不对？

先别急着怀疑 LoveIt。优先检查三件事：

• 图片本身是否已经被裁剪得很奇怪。
• 父级容器是否被额外限制了高度或宽度。
• 你有没有同时写了不该写的 height="auto"。

很多时候，问题并不是 shortcode 本身，而是你在别的地方又叠加了一层错误样式。

2. 为什么点击图片没法放大？

重点检查：

• lightgallery = true 是否真的开启。
• 你使用的是 LoveIt 原生 image shortcode，还是自写 HTML。
• 如果是原生 HTML，外层链接是否带了 class="lightgallery"。

点击不放大，通常不是图片路径错，就是画廊触发条件没满足。

3. src_s 和 src_l 到底值不值得写？

如果你只想插一张普通图，可以不写，直接只用 src。

但如果你已经准备了三张不同尺寸图，并且希望点击后获得更好的大图体验，那把 src_s 和 src_l 补上，是值得的。它会让点击后的浏览体验更完整，而不是仅仅打开一张原图链接那么生硬。

4. 图片文件名一定要 WebP 吗？

不一定，但对于博客场景，我依然推荐优先使用 WebP。它通常能兼顾清晰度和体积，更适合网页图片长期使用。

如果是正文截图、封面图、插画图，大多数情况下 WebP 都是更省心的选择。

九、我个人更推荐哪种方案？

如果站在“够用、稳定、好维护”的角度，我推荐你优先用 LoveIt 原生的 image shortcode。

原因很简单：

• 写法短。
• 和主题本身兼容最好。
• 点击放大体验自然。
• 不需要额外魔改主题文件。
• 对大多数博客文章来说已经足够。

如果你后面开始极度在意性能、流量和设备差异，再升级到 srcset + sizes 的原生 HTML 方案也不迟。

换句话说，先走稳，再走深。不要一上来就把简单问题做成复杂工程。

十、给想直接照抄的人：最终推荐写法

LoveIt 原生方案

代码展示版：

{{< 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="夜雨孤灯水墨画配图"
          src_s="/images/post-end/night-rain-lamp-800.webp"
          src_l="/images/post-end/night-rain-lamp-1600.webp"
          width="100%" >}}

更细致的响应式方案

<a href="/images/post-end/night-rain-lamp-1600.webp" class="lightgallery">
    <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;">
</a>

一个适合大多数人，一个适合继续深挖性能的人。你不必一次把所有路都走完，只需要先选对当下最适合自己的那条。

十一、写在最后

技术写作这件事，对我来说一直不只是“把答案贴出来”。更重要的是，把我走过的弯路、踩过的坑、曾经误解过的地方，也一起摊开写清楚。因为很多时候，真正消耗人的不是问题本身，而是那种反复试、反复错、反复怀疑自己是不是哪里又漏掉了什么的疲惫感。

如果这篇文章刚好帮你在某一个卡住的时刻，少绕了一点路，少浪费了一点时间，甚至只是少烦躁了一会儿，那它就已经有了价值。

愿我们都能在一地琐碎的技术问题里，慢慢把手上的工具用顺，也把自己的路走稳。

版本记录

• 2026-03-14：整理为梦行志风格版，保留实操步骤，也保留一点写给同行者的温度。

–全文完–

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

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

微信公众号：

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

我的邮箱📫：hero@oklife.me

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

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

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