为 Hexo 博客 Fluid 主题添加相册功能#

一、前期准备#

工具与思路
- 需理清文件路径关系（同级/上下级路径），避免路径错误。
- 借助工具辅助：代码问题可咨询 ChatGPT，或通过 Bing 搜索解决方案。

二、创建导航菜单#

1. 配置文件路径#

进入主题文件夹 hexo-theme-fluid，编辑配置文件 _config.yml。
也可以编辑配置文件_config.fluid.yml（推荐）

2. 添加菜单条目#

在 menu 字段下新增相册菜单，示例代码：

1
 menu:
2

3
    - { key: "home", link: "/", icon: "iconfont icon-home-fill" }
4

5
    - { key: "archive", link: "/archives/", icon: "iconfont icon-archive-fill" }
6

7
    - { key: "category", link: "/categories/", icon: "iconfont icon-category-fill" }
8

9
    - { key: "tag", link: "/tags/", icon: "iconfont icon-tags-fill" }
10

11
    - { key: "相册", link: "/photo/", icon: "iconfont icon-images" }
12

13
    - { key: "about", link: "/about/", icon: "iconfont icon-user-fill" }
14

15
    - { key: "links", link: "/links/", icon: "iconfont icon-link-fill" }

3. 菜单参数说明#

key：菜单显示名称（中文需注意多语言配置，可在 themes/hexo-theme-fluid/languages/zh-CN.yml 中添加 photo 对应翻译）。
link：菜单链接路径（如 /photo/ 或 /photos/，需与后续页面路径一致）。
icon：菜单图标（引用字体图标类名）。

4. 多语言配置（可选）#

在 themes/hexo-theme-fluid/languages/zh-CN.yml 中添加：

1
photo:
2
  menu: '相册'
3
  title: '相册'
4
  subtitle: '相册'

三、创建相册页面#

1. 目录结构#

在博客根目录 source 下新建 photo 文件夹（若路径为 photos，后续配置需同步修改）。

2. 新建页面文件#

在 photo 文件夹中创建 index.md，内容模板：

1
---
2

3
title: 图库
4

5
subtitle: 欢迎来到照片墙
6

7
layout: photo
8

9
published: 2024-04-1 12:44:07
10

11
---
12

13
## 欢迎来到我的图库。
14
---
15

16
<style>
17

18
.ImageGrid {
19

20
  width: 100%;
21

22
  max-width: 1040px;
23

24
  margin: 0 auto;
25

26
  text-align: center;
27

28
}
29

30
.card {
31

32
  overflow: hidden;
33

34
  transition: .3s ease-in-out;
35

36
  border-radius: 8px;
37

38
  background-color: rgba(180,180,180,0.2);
39

40
  padding: 1.4px;
41

42
}
43

44
.ImageInCard img {
45

46
  padding: 0;
47

48
  border-radius: 8px;
49

50
  width:100%;
51

52
  height:100%;
53

54
}
55

56
@media (prefers-color-scheme: dark) {
57

58
  .card {background-color: rgba(180,180,180,0.2);}
59

60
}
61

62
</style>
63

64
<div id="imageTab"></div>
65

66
<div class="ImageGrid"></div>
67

68
---
69

70
##### 相册页鸣谢：
71

72

73

74
[小晓de雨滴 - 为hexo博客Fluid主题添加相册功能](https://fxy5750.github.io/2024/04/05/30-hexo%E7%9B%B8%E5%86%8C%E5%8A%9F%E8%83%BD/#%E5%BC%95%E7%94%A8)
75

76
[四维树的博客 - Fluid主题添加相册功能](https://4dtree.github.io/2022/06/21/Hexo-Fluid%E4%B8%BB%E9%A2%98%E6%B7%BB%E5%8A%A0%E7%9B%B8%E5%86%8C%E5%8A%9F%E8%83%BD/)
77

78
[何十七 - hexo的fluid主题添加相册功能及自定义页面 ](https://hzx17.github.io/2022/07/14/hexo%E9%85%8D%E7%BD%AE/hexo%E7%9B%B8%E5%86%8C%E5%AE%9E%E7%8E%B0/)
79

80
[GISHAI - hexo的fluid主题添加瀑布流懒加载相册功能](https://gishai.top/blog/posts/798ba833.html)
81

82
[魏超 - 为 Hexo + Fluid 博客添加承载相册的页面](https://weichao.io/09dacc5ba02c/)

3. 关键配置说明#

layout: photo：指定页面布局为相册（若路径为 photos，需后续在 injector.js 中修改对应名称）。
<style> 标签：定义相册图片展示样式。

四、图片设置与存储#

1. 图片存储路径#

在 photo 文件夹中新建 images 文件夹，用于存放需展示的图片新建文件夹名称为你图片分类名称，你可以在photo文件夹下建立多个子文件夹分类图片。

2. 图床选择（当前方案）#

采用 本地存储，图片托管于 GitHub 或 Gitee。
GitHub可以考虑采用jsDelivr加速如何使用jsDelivr+Github 实现免费CDN加速? - 知乎。

五、创建图片处理脚本（phototool.js）#

1. 脚本功能#

生成图片尺寸、名称、路径等信息，需依赖 image-size 库。

2. 脚本代码#

1
const fs = require('fs-extra');
2

3
const path = require('path');
4

5
const imageSize = require('image-size');
6

7
// 相册目录（直接使用当前脚本所在目录）
8
const photoDir = __dirname;
9
// 支持的图片格式
10
const validExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'];
11

12

13
class Photo {
14

15
  constructor() {
16

17
    this.dirName = '';
18

19
    this.fileName = '';
20

21
    this.iconID = '';
22

23
  }
24

25
}
26

27

28

29
class PhotoGroup {
30

31
  constructor() {
32

33
    this.name = '';
34

35
    this.children = [];
36

37
  }
38

39
}
40

41

42

43
function createPlotIconsData() {
44

45
  const allPlots = [];
46

47
  const allPlotGroups = [];
48

49
  const plotJsonFile = path.join(__dirname, 'photosInfo.json');
50

51
  const plotGroupJsonFile = path.join(__dirname, 'photos.json');
52

53

54

55
  // 读取所有子目录（分类文件夹）
56

57
  fs.readdirSync(photoDir)
58

59
    .filter(item => {
60

61
      const itemPath = path.join(photoDir, item);
62

63
      return fs.statSync(itemPath).isDirectory() && item !== 'node_modules'; // 排除 node_modules
64

65
    })
66

67
    .forEach(dirName => {
68

69
      const dirPath = path.join(photoDir, dirName);
70

71
      const subfiles = fs.readdirSync(dirPath);
72

73
      const group = new PhotoGroup();
74

75
      group.name = dirName; // 文件夹名作为分类名
76

77
      allPlotGroups.push(group);
78

79

80

81
      subfiles.forEach(subfileName => {
82

83
        const imagePath = path.join(dirPath, subfileName);
84

85
        try {
86

87
          // 获取文件状态
88

89
          const stat = fs.statSync(imagePath);
90

91
          // 跳过空文件
92

93
          if (stat.size === 0) {
94

95
            console.log(`跳过空文件：${imagePath}`);
96

97
            return;
98

99
          }
100

101
          // 检查文件扩展名
102

103
          const ext = path.extname(subfileName).toLowerCase();
104

105
          if (!validExtensions.includes(ext)) {
106

107
            console.log(`跳过非图片文件：${imagePath}`);
108

109
            return;
110

111
          }
112

113
          // 处理图片
114

115
          const plot = new Photo();
116

117
          plot.dirName = dirName;
118

119
          plot.fileName = subfileName;
120

121
          // 获取图片尺寸
122

123
          const imgInfo = imageSize(imagePath);
124

125
          plot.iconID = `${imgInfo.width}.${imgInfo.height} ${subfileName}`;
126

127
          allPlots.push(plot);
128

129
          group.children.push(plot.iconID);
130

131
          console.log(`✅ 处理成功：${imagePath}`);
132

133
        } catch (error) {
134

135
          console.error(`❌ 处理失败：${imagePath}`, error.message);
136

137
        }
138

139
      });
140

141
    });
142

143

144

145
  // 保存结果
146

147
  fs.writeJSONSync(plotJsonFile, allPlots);
148

149
  fs.writeJSONSync(plotGroupJsonFile, allPlotGroups);
150

151
  console.log(`🎉 完成！共处理 ${allPlots.length} 张图片，生成 ${allPlotGroups.length} 个分类`);
152

153
}
154

155

156

157
createPlotIconsData();

3. 安装依赖#

在终端运行：

1
npm install image-size fs-extra path --save

4. 运行脚本#

在 photo 目录下的终端执行脚本，生成 photos.json 和 photosinfo.json 文件（用于相册渲染）。

1
node source/photo/phototool.js

注意事项：

所有路径需严格匹配，避免因大小写或拼写错误导致功能异常。
若修改相册路径（如 photo → photos），需同步更新导航菜单、页面布局、脚本路径等多处配置。

六、编写相册 JS 文件（`photoWall.js`）#

在 source/js/ 目录下创建该文件（无 js 文件夹则新建），代码用于渲染图片列表、实现分类切换和懒加载：

1
var imgDataPath = "/photo/photos.json"; // 分类信息JSON
2

3
var imgPath = "/photo/"; // 分类文件夹的根路径
4
// var imgPath = "https://cdn.jsdelivr.net/gh/Cenergy/images/gallery/"; //网络图片访问路径实例
5
var imgMaxNum = 50; // 图片显示数量
6

7

8

9
var windowWidth =
10

11
  window.innerWidth ||
12

13
  document.documentElement.clientWidth ||
14

15
  document.body.clientWidth;
16

17
if (windowWidth < 768) {
18

19
  var imageWidth = 145; // 图片显示宽度(手机端)
20

21
} else {
22

23
  var imageWidth = 250; // 图片显示宽度
24

25
}
26

27

28

29
const photo = {
30

31
  page: 1,
32

33
  offset: imgMaxNum,
34

35
  init: function () {
36

37
    var that = this;
38

39
    $.getJSON(imgDataPath, function (data) {
40

41
      that.render(that.page, data);
42

43
      that.eventListen(data);
44

45
    });
46

47
  },
48

49
  constructHtml(options) {
50

51
    const {
52

53
      imageWidth,
54

55
      imageX,
56

57
      imageY,
58

59
      name, // 分类名
60

61
      imgName,
62

63
      imgPath,
64

65
      imgNameWithPattern,
66

67
    } = options;
68

69
    // 重点修改：拼接完整路径 "/photo/分类名/图片.jpg"
70

71
    const fullImgPath = `${imgPath}${name}/${imgNameWithPattern}`;
72

73
    const htmlEle = `<div class="card lozad" style="width:${imageWidth}px">
74

75
                  <div class="ImageInCard" style="height:${
76

77
                    (imageWidth * imageY) / imageX
78

79
                  }px">
80

81
                    <a data-fancybox="gallery" href="${fullImgPath}"
82

83
                          data-caption="${imgName}" title="${imgName}">
84

85
                            <img  class="lazyload" data-src="${fullImgPath}"
86

87
                            src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
88

89
                            onload="lzld(this)"
90

91
                            lazyload="auto">
92

93
                    </a>
94

95
                  </div>
96

97
                  <p>${imgName}</p>
98

99
                </div>`;
100

101
    return htmlEle;
102

103
  },
104

105
  render: function (page, data = []) {
106

107
    this.data = data;
108

109
    if (!data.length) return;
110

111
    var html,
112

113
      imgNameWithPattern,
114

115
      imgName,
116

117
      imageSize,
118

119
      imageX,
120

121
      imageY,
122

123
      li = "";
124

125

126

127
    let liHtml = "";
128

129
    let contentHtml = "";
130

131

132

133
    data.forEach((item, index) => {
134

135
      const activeClass = index === 0 ? "active" : "";
136

137
      liHtml += `<li class="nav-item" role="presentation">
138

139
          <a class="nav-link ${activeClass} photo-tab" id="home-tab" photo-uuid="${item.name}" data-toggle="tab" href="#${item.name}"  role="tab" aria-controls="${item.name}" aria-selected="true">${item.name}</a>
140

141
        </li>`;
142

143
    });
144

145
    const [initData = {}] = data;
146

147
    const { children = [], name } = initData; // 获取分类名
148

149
    children.forEach((item, index) => {
150

151
      imgNameWithPattern = item.slice(item.indexOf(" ")+1);
152

153
      imgName = imgNameWithPattern.split("/").pop();
154

155
      imageSize = item.split(" ")[0];
156

157
      imageX = imageSize.split(".")[0];
158

159
      imageY = imageSize.split(".")[1];
160

161
      let imgOptions = {
162

163
        imageWidth,
164

165
        imageX,
166

167
        imageY,
168

169
        name, // 传递分类名
170

171
        imgName,
172

173
        imgPath,
174

175
        imgNameWithPattern,
176

177
      };
178

179
      li += this.constructHtml(imgOptions);
180

181
    });
182

183
    contentHtml += ` <div class="tab-pane fade show active"  role="tabpanel" aria-labelledby="home-tab">${li}</div>`;
184

185

186

187
    const ulHtml = `<ul class="nav nav-tabs" id="myTab" role="tablist">${liHtml}</ul>`;
188

189
    const tabContent = `<div class="tab-content" id="myTabContent">${contentHtml}</div>`;
190

191

192

193
    $("#imageTab").append(ulHtml);
194

195
    $(".ImageGrid").append(tabContent);
196

197
    this.minigrid();
198

199
  },
200

201
  eventListen: function (data) {
202

203
    let self = this;
204

205
    var html,
206

207
      imgNameWithPattern,
208

209
      imgName,
210

211
      imageSize,
212

213
      imageX,
214

215
      imageY,
216

217
      li = "";
218

219
    $('a[data-toggle="tab"]').on("shown.bs.tab", function (e) {
220

221
      $(".ImageGrid").empty();
222

223
      const selectId = $(e.target).attr("photo-uuid");
224

225
      const selectedData = data.find((data) => data.name === selectId) || {};
226

227
      const { children, name } = selectedData; // 获取分类名
228

229
      let li = "";
230

231
      children.forEach((item, index) => {
232

233
        imgNameWithPattern = item.split(" ")[1];
234

235
        imgName = imgNameWithPattern.split("/").pop();
236

237
        imageSize = item.split(" ")[0];
238

239
        imageX = imageSize.split(".")[0];
240

241
        imageY = imageSize.split(".")[1];
242

243
        let imgOptions = {
244

245
          imageWidth,
246

247
          imageX,
248

249
          imageY,
250

251
          name, // 传递分类名
252

253
          imgName,
254

255
          imgPath,
256

257
          imgNameWithPattern,
258

259
        };
260

261
        li += self.constructHtml(imgOptions);
262

263
      });
264

265
      $(".ImageGrid").append(li);
266

267
      self.minigrid();
268

269
    });
270

271
  },
272

273
  minigrid: function () {
274

275
    var grid = new Minigrid({
276

277
      container: ".ImageGrid",
278

279
      item: ".card",
280

281
      gutter: 12,
282

283
    });
284

285
    grid.mount();
286

287
    $(window).resize(function () {
288

289
      grid.mount();
290

291
    });
292

293
  },
294

295
};
296

297
photo.init();

创建注入器文件（`injector.js`）#

在博客根目录新建 scripts/injector.js，用于加载相册所需的 CSS/JS 文件：

1
//相册页面
2
const { root: siteRoot = "/" } = hexo.config;
3
// layout为photo的时候导入这些js与css
4
hexo.extend.injector.register(
5
"body_end",
6
`
7

8
<link rel="stylesheet" href="https://cdn.staticfile.org/fancybox/3.5.7/jquery.fancybox.min.css">
9
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/minigrid.min.js"></script>
10
<script src="https://cdn.staticfile.org/fancybox/3.5.7/jquery.fancybox.min.js"></script>
11
<script src="https://cdn.bootcdn.net/ajax/libs/lazyloadjs/3.2.2/lazyload.js"></script>
12
<script defer src="${siteRoot}js/photoWall.js"></script>
13
`,
14
"photo"
15
);
16

17
// CDN加载方案，目前上述文件使用CDN加载方案；
18
// 本地加载方案，这个方案就是把上面CDN文件一个一个存到 js目录下，仅此而已，我用的这个方案，感觉更靠谱些，不用担心CDN访问时候出现 404
19
// <link rel="stylesheet" href="/js/jquery.fancybox.min.css">
20
// <script src="/js/minigrid.min.js"></script>
21
// <script src="/js/jquery.fancybox.min.js"></script>
22
// <script src="/js/lazyload.js"></script>
23
// <script defer src="${siteRoot}js/photoWall.js"></script>

后期维护与扩展#

添加新图片：
- 将图片复制到 photo/images 目录。
- 重新运行 phototool.js 生成最新元数据：
  Terminal window
```
1
node source/photo/phototool.js
```
共用图片路径：
修改 photoWall.js 中的 imgPath 为博客通用图片路径（如 /img/images/）。

多分类管理：
在 photos.json 中按分类组织图片，示例结构：

1
[
2
  {
3
    "name": "壁纸",
4
    "children": ["10000.4220 【哲风壁纸】WLOP-WLOP作品.png"]
5
  },
6
  {
7
    "name": "images",
8
    "children": ["800.600 旅行照.jpg", "1024.768 风景.png"]
9
  }
10
]

目录结构参考#

1
blog
2
├─ _config.fluid.yml
3
├─ scripts/
4
│  └─ injector.js          # 注入器配置
5
├─ source/
6
│  ├─ photo/
7
│  │  ├─ index.md         # 相册页面
8
│  │  ├─ images/           # 图片存储目录
9
|  |  ├─ 壁纸/             # 图片存储目录
10
│  │  ├─ phototool.js     # 图片处理脚本
11
│  │  └─ photos*.json     # 自动生成的元数据文件
12
│  └─ js/
13
│     └─ photoWall.js     # 相册逻辑代码
14
└─ themes/
15
   └─ hexo-theme-fluid/
16
      ├─ _config.yml       # 主题配置文件
17
      └─ languages/
18
         └─ zh-CN.yml      # 多语言配置