# 手把手教程：让 Hugo LoveIt 主题文章图片自适应宽度 + 点击放大高清图
{{< music auto="https://music.163.com/#/playlist?id=12472829847" >}}
有些技术问题，表面上只是一个参数没写对，背后却可能藏着半天、一天，甚至更久的绕路和怀疑。这个问题就是这样：我原本只是想让 Hugo + LoveIt 主题里的文章图片，既能自动适应正文宽度，又能保留点击放大查看高清图的能力，结果前前后后折腾了十几个小时，才把这件事真正理顺。
写下这篇文章，不只是为了记录一个技术解法，更是想把那些我已经踩过的坑、绕过的弯、反复试错后的结论，整理成一条对后来者更平坦一点的路。如果你此刻也正卡在这里，希望这篇文章能帮你省下时间，也省下一点焦躁。
***
## 一、我们到底想实现什么效果？
先把目标说清楚，否则很容易一边改配置，一边越改越乱。
如果你和我一样，想做的是博客文章里的普通配图，那大概率你真正需要的是下面这四件事：
- 图片能随着正文内容区宽度自动缩放，在手机和电脑上都不溢出。
- 图片保持原始比例，不被拉伸，也不被压扁。
- 点击图片以后，能够弹出更高清的大图查看。
- 写法尽量简单，不去魔改主题底层模板。
看起来像一个需求，其实是两层逻辑：**页面里怎么显示**，以及**点击后怎么查看大图**。很多人之所以被绕进去，就是把这两件事混在了一起。
***
## 二、先说结论：最稳妥的方案是什么？
如果你只想快速做对，那就直接用 LoveIt 原生的 `image shortcode`，并且只加一个关键参数：
```html
{{}}
```
真正插图时，把上面的转义示例换回可执行写法即可：
```html
{没这字{< 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]` 里确认这一项存在：
```toml
[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 的常见写法，会很自然地写出：
```html
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 已经足够。如果你想进一步追求真正的响应式加载，那就要进入下一步。
***
## 七、如果你想更进一步：真正的响应式加载怎么做？
详细的可用看我写的这篇文档：
[图片相关设置](https://www.oklife.me/2025/11/03/code-art-studio/image-loading/#33-%E5%AE%9E%E7%8E%B0%E5%93%8D%E5%BA%94%E5%BC%8F%E5%9B%BE%E7%89%87%E7%9A%84%E5%8A%9F%E8%83%BD%E9%AB%98%E7%BA%A7%E6%8A%80%E5%B7%A7/ "点击跳转")
所谓真正的响应式加载，不只是图片视觉上缩小或放大，而是浏览器根据设备宽度和网络状况，主动去选更合适的图片文件。
比如：
- 手机加载 800px
- 平板加载 1200px
- 桌面端加载 1600px
要做到这一点，更适合直接写原生 HTML：
```html
```
这段代码真正解决的是“加载哪一张图”这个问题。
- `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 原生方案
代码展示版：
```html
{{}}
```
实际使用版：
```html
{删掉这字{< 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%" >}}
```
### 更细致的响应式方案
```html
```
一个适合大多数人，一个适合继续深挖性能的人。你不必一次把所有路都走完，只需要先选对当下最适合自己的那条。
***
## 十一、写在最后
技术写作这件事，对我来说一直不只是“把答案贴出来”。更重要的是，把我走过的弯路、踩过的坑、曾经误解过的地方，也一起摊开写清楚。因为很多时候，真正消耗人的不是问题本身，而是那种反复试、反复错、反复怀疑自己是不是哪里又漏掉了什么的疲惫感。
如果这篇文章刚好帮你在某一个卡住的时刻，少绕了一点路，少浪费了一点时间，甚至只是少烦躁了一会儿，那它就已经有了价值。
愿我们都能在一地琐碎的技术问题里，慢慢把手上的工具用顺，也把自己的路走稳。
***
**版本记录**
- 2026-03-14：整理为梦行志风格版，保留实操步骤，也保留一点写给同行者的温度。
***
--全文完--
***
> **“同频之人，终会相遇；同行之路，终有光亮。”**
{{< typeit tag=h4 >}}
**“愿与身处同境、灵魂同频、砥砺前行的你相遇相伴，倾听彼此的故事与困惑，分享心路与感悟，在逆境中自救破局的路上彼此陪伴、相互照亮、同行向前,一起走向重生与新生。”**...
{{< /typeit >}}
{{< admonition type=question title="若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：" open=true >}}
> **微信公众号：**
> **私人微信号(有验证)：oklife_1314**
> **我的邮箱📫：**
>
{{< /admonition >}}
***
{{< admonition type=success title="希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。" open=true >}}
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自https://oklife.me。
{{< /admonition >}}
***
> **“同频之人，终会相遇；同行之路，终有光亮。”**
{{< typeit tag=h4 >}}
**“愿与身处同境、灵魂同频、砥砺前行的你相遇相伴，倾听彼此的故事与困惑，分享心路与感悟，在逆境中自救破局的路上彼此陪伴、相互照亮、同行向前,一起走向重生与新生。”**...
{{< /typeit >}}
{{< admonition type=question title="若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：" open=true >}}
> **微信公众号：**
> **私人微信号(有验证)：oklife_1314**
> **我的邮箱📫：