踩坑记录 - 使用 hexo 搭建博客

感觉写这个还是比较有必要的。2024.9.17 配置完成的博客，现在作一下经验总结。持续更新。

前置

  • 安装 Git。https://git-scm.com/。
  • 安装 nodejs 新版。https://nodejs.org/en/download/。这里当时以为用 nvm 升级，结果 nvm 只有旧版本，不要用。
  • 安装 Hexo。npm install hexo -g。
  • 安装一键部署包。npm install --save hexo-deployer-git。

配置 SSH Key

这一段，我是直接参照 https://www.cnblogs.com/chenlove/p/15058170.html（不如说整个流程都是参照它的），直接做即可。

搭建

仍然可以查看上面这一篇，或者查看 Hexo 官方文档 https://hexo.io/zh-cn/docs/setup。整体的逻辑就是用 npm 管理所有的软件包。

编写博客

使用 Markdown。

一般有一个 front matter，就是在每篇文章的最上方有这样的文字：

1
2
3
4
5
6
7
8
9
---
layout: post
title: ...
date: ...
tags:
  - ...
  - ...
categories: ...
---

其他是正常的。

about 页的 layout 设置成 about。

渲染

为了支持 KaTeX 渲染，使用了 hexo-math 和 hexo-renderer-markdown-it-plus 插件。

我目前使用的主题是 Fluid，官方文档很全面，整体也很好看。不过有一些细节文档没有提及，在下面贴出我的 _config.yml 和 _config.fluid.yml（可能不随时更新）。事实上至今我也不知道到底谁管的大谁管的小，反正都提供参考就是了。

附加功能

评论使用 giscus 插件，网页统计使用 busuanzi，加密使用 hexo-blog-encrypt 插件，具体配置直接看下方的主题配置文件吧，就跟在 post 一段后面。

配置文件

_config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: SunsetGlow95's Blog
subtitle: SunsetGlow95's Blog
description: SunsetGlow95's Blog
keywords:
author: SunsetGlow95
language: zh-CN
timezone: Asia/Shanghai

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: http://SunsetGlow95.github.io
# permalink: :year/:month/:day/:title/
permalink: :title/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: true # Set to false to remove trailing '.html' from permalinks

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:

# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
titlecase: false # Transform title into titlecase
external_link:
  enable: true # Open external links in new tab
  field: site # Apply to the whole site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
syntax_highlighter:
highlight:
  enable:
  line_number: true
  auto_detect: false
  tab_replace: ''
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''

# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
index_generator:
  path: ''
  per_page: 10
  order_by: -date

# Category & Tag
default_category: uncategorized
category_map: 游记, 学习笔记, 题解, 闲话
tag_map:

# Metadata elements
## https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
meta_generator: true

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD
time_format: HH:mm:ss
## updated_option supports 'mtime', 'date', 'empty'
updated_option: 'mtime'

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10
pagination_dir: page

# Include / Exclude file(s)
## include:/exclude: options only apply to the 'source/' folder
include:
exclude:
ignore:

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: fluid

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repository: git@github.com:SunsetGlow95/SunsetGlow95.github.io.git
  branch: main

post:
  math:
    enable: true
    specific: true
    engine: katex

archive_generator:
    enabled: true
    per_page: 0
    yearly: false
    monthly: false
    daily: false

markdown_it_plus:
    pre_class: ''
    langPrefix: ''



# Security
encrypt: # hexo-blog-encrypt
  abstract: ''
  message: '您好，请输入密码（我的真名全拼）'
  wrong_pass_message: '抱歉，这个密码看着不太对，请再试试。'
  wrong_hash_message: '抱歉，这个文章不能被校验，不过您还是能看看解密后的内容。'

_config.fluid.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: SunsetGlow95's Blog
subtitle: SunsetGlow95's Blog 
description: SunsetGlow95's Blog
keywords:
author: SunsetGlow95
language: zh-CN
timezone: Asia/Shanghai

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: http://SunsetGlow95.github.io
# permalink: :year/:month/:day/:title/
permalink: :title/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: true # Set to false to remove trailing '.html' from permalinks

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:

# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
titlecase: false # Transform title into titlecase
external_link:
  enable: true # Open external links in new tab
  field: site # Apply to the whole site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
syntax_highlighter: highlight.js
highlight:
  enable: true
  line_number: true
  auto_detect: false
  tab_replace: ''
prismjs:
  enable: false
  preprocess: true
  line_number: true
  tab_replace: ''
# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
index_generator:
  path: ''
  per_page: 10
  order_by: -date

# Category & Tag
default_category: uncategorized
category_map:
tag_map:

# Metadata elements
## https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
meta_generator: true

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD
time_format: HH:mm:ss
## updated_option supports 'mtime', 'date', 'empty'
updated_option: 'mtime'

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10
pagination_dir: page

# Include / Exclude file(s)
## include:/exclude: options only apply to the 'source/' folder
include:
exclude:
ignore:

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: fluid

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repository: git@github.com:SunsetGlow95/SunsetGlow95.github.io.git
  branch: main

favicon: https://s2.loli.net/2024/10/29/lUILWGcexEiNZjh.png

index:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg
  slogan:
    enable: true
    text: 热忱真理。
  auto_excerpt:
    enable: false

navbar:
  blog_title: SunsetGlow95's Blog
  menu:
    - {
      key: 'home',
      link: '/',
      icon: 'iconfont icon-home-fill',
    }
    - {
      key: 'archive',
      link: '/archives/',
      icon: 'iconfont icon-archive-fill',
    }
    - {
      key: 'category',
      link: '/categories/',
      icon: 'iconfont icon-category-fill',
    }
    - {
      key: 'tag',
      link: '/tags/',
      icon: 'iconfont icon-tags-fill',
    }
    - {
      key: 'links',
      link: '/links/',
      icon: 'iconfont icon-link-fill',
    }
    - {
      key: 'about',
      link: '/about/',
      icon: 'iconfont icon-user-fill',
    }

archive:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg

category:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg

tag:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg

post:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg
  math:
    enable: true
    specific: true
    engine: katex
  comments:
    enable: true
    type: giscus
  meta:
    views:
      enable: true
      source: "busuanzi"
      format: "{} 次"

# giscus: convert the given js into yaml
# 仅供参考，请使用自己在 giscus 获得的标签信息
giscus:
  repo: SunsetGlow95/SunsetGlow95.github.io
  repo-id: R_kgDOMxNR0g
  category: Announcements
  category-id: DIC_kwDOMxNR0s4Co1Jo
  mapping: pathname
  strict: 0
  reactions-enabled: 1
  emit-metadata: 0
  input-position: bottom
  theme: noborder_gray
  lang: zh-CN
  crossorigin: anonymous

# web analytics
web_analytics:
  enable: true
footer:
  statistics:
    enable: true
    source: "busuanzi"
    pv_format: "总访问量 {} 次"
    uv_format: "总访客数 {} 人"

# links page
links:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg
  items:
    - {
      title: 'Project Euler',
      intro: '数学趣题。',
      avatar: 'https://pe-cn.github.io/images/32x32.png',
      link: 'https://pe-cn.github.io',
    }
    - {
      title: 'Euclidea',
      intro: '尺规作图趣题。',
      avatar: 'https://www.euclidea.xyz/game/assets/favicon.png',
      link: 'https://www.euclidea.xyz/',
    }
    - {
      title: 'csacademy graph editor',
      intro: '图论编辑器。',
      avatar: 'https://csacademy.com/static/favicon.png',
      link: 'https://csacademy.com/app/graph_editor',
    }
    - {
      title: 'tldraw',
      intro: '在线白板。',
      avatar: 'https://www.tldraw.com/apple-touch-icon-180x180.svg',
      link: 'https://www.tldraw.com',
    }
    - {
      title: 'sm.ms',
      intro: '免费图床。',
      avatar: 'https://sm.ms/favicon-32x32.png',
      link: 'https://sm.ms',
    }
    - {
      title: 'latexlive',
      intro: '在线 LaTeX 公式编辑器。',
      link: 'https://www.latexlive.com',
    }
    - {
      title: 'caijianhong - 博客园',
      intro: '大神的博客。',
      avatar: 'https://cdn.luogu.com.cn/upload/usericon/509229.png',
      link: 'https://www.cnblogs.com/caijianhong',
    }
    - {
      title: "Exber's Blog",
      intro: '大神的博客。',
      avatar: 'https://cdn.luogu.com.cn/upload/usericon/251130.png',
      link: 'https://rebxe.github.io',
    }

# about page
about:
  banner_img: https://s2.loli.net/2024/10/21/iC5uDOy7pe3PzJw.jpg
  avatar: https://s2.loli.net/2024/10/29/gWdDbIaXM4Lrc53.png
  name: "SunsetGlow95"
  intro: "OI / 计算机 / 数学 / 音乐 / 音游 / 魔方"
  icons:
    - {
      class: 'iconfont icon-codeforces',
      link: 'https://codeforces.com/profile/SunsetGlow95',
      tip: 'Codeforces'
    }
    - {
      class: 'iconfont icon-bilibili',
      link: 'https://space.bilibili.com/483357008',
      tip: 'Bilibili'
    }

# dark mode
dark_mode:
  enable: true
  default: auto

如果在加入 hexo-renderer-markdown-it-plus 后未将 fluid 语言调整为 zh-cn，将会变成德语，但不知道为啥。

我一开始尝试过其他主题，其中觉得比较好看的只有 particlex。但是它不支持 hexo-renderer-markdown-it-plus，代码高亮会死掉。开发者说推荐的渲染器是 hexo-renderer-pandoc，不过我没整成，懒了。

默认主题是 landscape。

维护

以下全部都是工作目录在博客目录下，终端的命令。

  • 清空：hexo clear/hexo cl。
  • 生成网页：hexo generate/hexo g。（它是惰性的，如果需要全部刷新需要先执行 hexo cl。）
  • 本地预览：hexo server/hexo s。
  • 上传到 GitHub：hexo deploy/hexo d。
踩坑记录
踩坑记录 - 使用 hexo 搭建博客
http://sunsetglow95.github.io/tech-blog-building/
作者
SunsetGlow95
发布于
2024年9月27日
许可协议