解决Hexo相册滚动时图片消失的问题：从现象到根源的排查记录

在使用 Hexo 搭建单机游戏相册页面时，遇到了一个有趣的问题：浏览 “黑神话悟空” 分类下的图片时，向下滚动页面，上方的图片会突然消失；向上滚动时，消失的图片又会重新出现。经过一番排查，终于找到原因并解决，特此记录整个过程。

一、问题现象

具体表现

页面结构：使用 Hexo 的{% gallery %}标签展示图片，按游戏分类（奥日与萤火意志、黑神话悟空、战神）分组。如下图：
异常场景：在 “黑神话悟空” 分类下，当图片数量超过10张时，滚动页面到第 10 张之后，上方的图片会突然消失；再向上滚动一下，消失的图片又会重新加载出现。
其他分类：“奥日与萤火意志”（15 张）和 “战神”（10 张）中，“战神” 分类因图片数量刚好为 10 张，未出现异常；“奥日与萤火意志” 偶尔也会出现，但因滚动速度较慢，现象不明显。

二、问题分析

针对 “滚动时图片消失” 的现象，初步推测与图片加载机制或组件逻辑有关，逐一排查如下：

1. 图片懒加载（Lazy Loading）的影响

现代博客通常会启用图片懒加载（仅加载可视区域的图片），但正常的懒加载只会 “延迟加载”，不会 “卸载已加载的图片”。

排查：通过浏览器开发者工具（F12）查看图片元素，发现图片使用data-lazy-src属性实现懒加载，但未找到 “卸载不可见图片” 的配置。
结论：懒加载是优化手段，并非直接原因。

2. CSS 样式导致的 “视觉隐藏”

若父容器或图片本身的 CSS 样式存在特殊设置，可能导致滚动时图片被截断或隐藏：

排查：检查相册容器的样式，发现gallery-container使用默认布局，无overflow: hidden或position: fixed等异常属性；图片元素也无display: none或opacity: 0的动态样式。
结论：CSS 样式无异常。

3. 相册组件的 “按需加载” 逻辑

核心怀疑点：相册组件可能存在 “加载数量限制”，超过限制后自动卸载上方图片（为了优化性能）。

排查：查看 Hexo 生成的 HTML 代码，这里我的路径是“根目录/public/gallery/game/index.html”，发现相册容器gallery-container有两个关键属性：

<div class="gallery-container" 
     data-type="data" 
     data-limit="10"  <!-- 限制最多加载10张图片 -->
     data-first="10"> <!-- 初始加载10张图片 -->

对应现象：“黑神话悟空” 有 14 张图片，超过data-limit="10"，因此滚动时会卸载超出范围的图片；“战神” 刚好 10 张，未触发卸载逻辑。
结论：这是导致图片消失的核心原因。

三、解决过程

1. 尝试修改组件参数

相册组件的data-limit和data-first属性控制加载数量，因此我尝试在 Markdown 中修改这两个参数：

<!-- 原标签：默认参数 -->
{% gallery %}
<!-- 图片列表 -->
{% endgallery %}

<!-- 修改后：增加加载限制 -->
{% gallery data-limit=20 data-first=14 %}  <!-- 黑神话悟空有14张图 -->
<!-- 图片列表 -->
{% endgallery %}

2. 发现参数未生效的新问题

重新生成页面后，发现 HTML 中参数未生效，反而被错误地解析到data-button属性中：

<!-- 错误的生成结果 -->
<div class="gallery-container" 
     data-type="data" 
     data-button="data-limit=20 data-first=14"  <!-- 参数被错误赋值 -->
     data-limit="10"  <!-- 仍为默认值10 -->
     data-first="10">

3. 正确的参数设置方式

我仔细查阅了一下文档，发现{% gallery %} 标签其实支持三个参数，专门用来控制图片加载和显示的，具体说明如下：

参数	解释
lazyload	【可选】点击按钮加载更多图片，填写 true/false。默认为`false`。
rowHeight	【可选】图片显示的高度，如果需要一行显示更多的图片，可设置更小的数字。默认为`220`。
limit	【可选】每次加载多少张照片。默认为`10`。

这里有个对应关系得记一下：rowHeight 对应生成 HTML 里的 data-limit，limit 对应 data-first。参数的格式得按顺序写，用逗号隔开：

1
2
3

{% gallery [lazyload],[rowHeight],[limit] %}
<!-- 这里放 markdown 图片格式 -->
{% endgallery %}

知道了这个，我就直接去 “根目录 /source/gallery/game/index.md” 里改了，给每个相册的 {% gallery %} 都加上 false,220,20：

{% gallery false,220,20 %}  <!-- 意思是：不启用点击加载，图片高度220，每次加载20张（比实际的14张多） -->
![黑神话悟空1](https://a1.boltp.com/2025/08/22/68a80e202d1b2.jpg)
![黑神话悟空2](https://a1.boltp.com/2025/08/22/68a80e2040a50.jpeg)
<!-- 其余12张图片 -->
{% endgallery %}

改完执行生成命令：

1	`hexo clean && hexo generate`

再看生成的 HTML，参数终于对了，data-limit 和 data-first 都是我设置的数值：

4. 验证结果

启动本地服务看看效果：

1	`hexo server`

访问 http://localhost:4000 翻了翻页面，所有图片都稳稳当当的，怎么滚动都不会消失了～

四、总结与注意事项

参数设置原则：
对于data-limit和data-first，建议设置为 “大于实际图片数量的值”，避免组件因 “超出限制” 触发卸载逻辑。
排查问题的思路：
遇到页面元素异常时，优先通过浏览器开发者工具查看生成的 HTML 代码，对比 “正常” 与 “异常” 场景的差异（如本文中data-limit的默认值 10 与图片数量的关系）。
插件文档的重要性：
本次问题的核心是对{% gallery %}标签参数不熟悉，后续使用新插件时，应先查阅官方文档（如hexo-butterfly-tag-plugins-plus的参数说明）。
图片链接稳定性：
若使用第三方图床（如本次的a1.boltp.com），需确保链接长期有效，避免因链接失效导致 “图片加载失败” 的次生问题。