I have tried my best to make this look like the title of a HYPERFLIP song, but it is still not long enough.
0%

Hello Hexo

发表于 更新于 阅读次数： Valine：
本文字数： 3.7k 阅读时长 ≈ 18 分钟

总结一下在 GitHub Pages 用 Hexo 框架建站的流程以及过程中踩过的坑。

NexT 主题

更换 NexT 主题

NexT 是 Hexo 最受欢迎的主题之一，支持多种样式和配置。
打开任意命令行解释器，在 Blog 的根目录执行

1
git clone git@github.com:theme-next/hexo-theme-next.git themes/next

或者到 NexT 主题的 GitHub 仓库下载正式发行的压缩包，解压到 themes/next 目录中。
之后编辑 _config.yml 文件中的 themes 配置。

1
theme: next

修改 NexT 主题模板

编辑 themes/next/_config.yml 文件中的 scheme 配置。 

1
scheme: Gemini

修改亮色/暗色模式

编辑 themes/next/_config.yml 文件中的 darkmode 配置。 

1
darkmode: true

网站个人信息配置

网站基本信息

编辑 _config.yml 文件。可以修改主标题、副标题、简介、关键词、作者名称、语言、时区、访问 URL 等配置。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Site
title: scxs1388's Blog # 网站主标题
subtitle: Everything happens for the best # 网站副标题
description: Falling into singularity # 简介
keywords: # 关键词 (搜索用)
author: scxs1388 # 作者名称
language: zh-CN # 语言
timezone: Asia/Shanghai # 时区

# URL
url: https://scxs1388.github.io # 访问的 url

# Writing
highlight: # 代码高亮
  enable: true
  line_number: true
  auto_detect: true

网站 Favicon

配置网站的浏览器标签页图标。
编辑 themes/next/_config.yml 文件中的 favicon 配置。
可以设置为在线或本地图片，默认本地图片存储目录为 themes/next/source/images。如果选择使用本地图片，在网站部署后的图片存储目录为 /images，在编辑配置时需要注意。

头像 Avatar

侧边栏添加个人头像。
编辑 themes/next/_config.yml 文件中的 avatar 配置。

1
2
3
4
avatar:
  url: /images/avatar.jpg # 本地图片路径
  rounded: true # 圆形边框
  rotated: false # 光标hover可旋转，不建议

社交账号链接

导航栏/侧边栏添加个人社交账号链接。
编辑 themes/next/_config.yml 文件中的 social 配置。

1
2
3
social:
  GitHub: https://github.com/scxs1388 || fab fa-github
  E-Mail: mailto:scxs1388@gmail.com || fa fa-envelope

Creative Commons

配置网站的 CC 协议。
编辑 themes/next/_config.yml 文件中的 creative_commons 配置。

1
2
3
4
5
creative_commons:
  license: by-nc-sa ## cc协议
  size: small # 大小
  sidebar: true # 侧边栏显示
  post: true # 文章结尾显示

网站页面配置

导航栏/侧边栏

配置导航栏/侧边栏的栏目和外观。
编辑 themes/next/_config.yml 文件中的 menu 配置。

1
2
3
4
5
6
7
8
9
menu:
  home: / || fa fa-home # 主页
  about: /about/ || fa fa-user # 关于
  tags: /tags/ || fa fa-tags # 文章 tag
  categories: /categories/ || fa fa-th # 文章类别
  archives: /archives/ || fa fa-archive # 文章归档
menu_settings:
  icons: true # 显示icon
  badges: true # 显示相应分类的数量

网页尾栏

更改网页尾栏的信息。
编辑 themes/next/_config.yml 文件中的 footer 配置。 

1
2
3
4
5
6
7
footer:
  since: 2021 # 网站建立时间
  icon:
    name: fa fa-heart
    animated: true
    color: "#ff0000"
  powered: true

GitHub 标识

设置网站右上角的 GitHub 标识。

编辑 themes/next/_config.yml 文件中的 github_banner 配置。

1
2
3
4
github_banner:
  enable: true
  permalink: https://github.com/scxs1388
  title: Follow me on GitHub

Tag icon

为文章底部的每个 Tags 前添加一个 icon。
编辑 themes/next/_config.yml 文件中的 tag_icon 配置。 

1
tag_icon: true

各种字体

设置网站的字体。包括文字样式，文字大小，在线字体 host 等。

编辑 themes/next/_config.yml 文件中的 font 配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
font:
  enable: true
  host: https://fonts.font.im
  global: # 全局字体 (指 <body> 内的所有元素)
    external: true # 设为 true 表示启用在线字体 host
    family: Lato
    size: 0.84
  title: # 网站主标题的字体
    external: true
    family: Roboto Slab
    size:
  headings: # 标题字体 (<h1> 到 <h6>)
    external: true
    family: Roboto
    size:
  posts: # 文章字体
    external: true
    family: Roboto
  codes: # 代码块字体
    external: true
    family: Input Mono  # Source Code Pro  # JetBrains Mono

页面加载进度条

启用页面加载时的进度条显示。
编辑 themes/next/_config.yml 文件中的 pace 配置。

1
2
3
pace:
  enable: true
  theme: minimal

注意，有时会出现 pace.min.css 和 pace.min.js 文件缺失的情况。此时需要在 themes/next/_config.yml 文件的 vendors 配置中设置CDN的地址，或者手动添加这两个文件到 themes/next/source/lib/pace 目录中。

文章功能配置

公式 MathJax

启用 MathJax 编写公式。
编辑 themes/next/_config.yml 文件中的 math 配置。

1
2
3
4
5
math:
  mathjax:
    enable: true # 一般用 mathjax 足够了
  katex:
    enable: true # 可以设成 false

高级 Markdown 渲染

启用 Markdown-it 作为渲染引擎来解析 Markdown 文本。
打开命令行，在 Blog 的根目录执行 

1
2
npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-markdown-it --save

编辑 _config.yml 文件，添加 markdown 配置。 

1
2
markdown:
  renderer: markdown-it

图片浏览插件 Fancybox

查看文章图片时使用 FancyBox 插件。
编辑 themes/next/_config.yml 文件中的 fancybox 配置。

1
fancybox: true

在某些情况下，我们可能不希望所有图片都启用 Fancybox 功能。编辑 themes/next/source/js/src/utils.js 文件，找到 wrapImageWithFancyBox 函数，在特定位置添加一行代码：

1
2
3
4
5
6
7
8
  wrapImageWithFancyBox: function() {
    document.querySelectorAll('.post-body :not(a) > img, .post-body > img').forEach(element => {
      var $image = $(element);
      // ↓ 在这里添加一行代码
      if ($image.hasClass('nofancybox')) return;
      var imageLink = $image.attr('data-src') || $image.attr('src');
      var $imageWrapLink = $image.wrap(`<a class="fancybox fancybox.image" href="${imageLink}" itemscope itemtype="http://schema.org/ImageObject" itemprop="url"></a>`).parent('a');
...

在写文章时，如果不希望某张图片启用 Fancybox 功能，可以在该图片的 <img> 标签中添加 nofancybox 类。

字数统计插件

打开命令行，在 Blog 的根目录执行

1
2
npm install hexo-word-counter --save
hexo clean

编辑 _config.yml 文件，添加 symbol_count_time 配置。 

1
2
3
4
5
6
7
8
symbols_count_time:
  symbols: true
  time: true
  total_symbols: true
  total_time: true
  exclude_codeblock: false
  wpm: 200
  suffix: "mins"

评论插件 Valine (不建议使用)

添加 Valine 评论系统。Valine 是基于 LeanCloud 云服务的前端评论系统，要启用 Valine 需要事先在 LeanCloud 注册并创建一个应用获取 Appid 和 AppKey。
上述步骤完成之后，编辑 themes/next/_config.yml 文件中的 valine 配置。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
valine:
  enable: true
  appid:  # Your leancloud application appid
  appkey: # Your leancloud application appkey
  notify: false # Mail notifier
  verify: false # Verification code
  placeholder: Just go go # Comment box placeholder
  avatar: mm # Gravatar style
  guest_info: nick,mail,link # Custom comment header
  pageSize: 10 # Pagination size
  language: zh-cn # Language, available values: en, zh-cn
  visitor: true # Article reading statistic
  comment_count: true # If false, comment count will only be displayed in post page, not in home page
  recordIP: false # Whether to record the commenter IP

由于 Valine 评论系统完全基于 JavaScript 前端实现，评论内容不会受到服务器端的验证，因此可能会存在垃圾评论的情况。现在 Valine 已经不再建议使用，可以转而使用 Waline 等其他评论系统。

站内搜索

启用站内搜索需要安装hexo-generator-searchdb 插件。
打开命令行，在 Blog 的根目录执行

1
npm install hexo-generator-searchdb --save

之后编辑 themes/next/_config.yml 文件中的 local_search 配置。

1
2
local_search:
  enable: true

阅读进度条和进度显示

启用阅读进度条和进度显示。
编辑 themes/next/_config.yml 文件中的 back2top 和 reading_progress 配置。

1
2
3
4
5
6
7
8
9
10
back2top:
  enable: true
  sidebar: false
  scrollpercent: true

reading_progress:
  enable: true
  position: top
  color: "#37c6c0"
  height: 3px

文章隐藏

启用文章隐藏功能可以通过修改文章生成的源代码来实现，为了方便可以安装hexo-hide-posts 插件。
打开命令行，在 Blog 的根目录执行 

1
npm install hexo-hide-posts --save

之后编辑 _config.yml 文件，添加： 

1
2
3
4
5
6
7
8
9
10
# hexo-hide-posts
hide_posts:
  enable: true
  # Change the filter name to fit your need
  filter: hidden
  # Generators which you want to expose all posts (include hidden ones) to.
  # Common generators: index, tag, category, archive, sitemap, feed, etc.
  public_generators: []
  # Add "noindex" meta tag to prevent hidden posts from being indexed by search engines
  noindex: true

在写文章时，如果想要隐藏文章，在 front-matter 添加 hidden: true 即可。

网站美化 (进阶)

更换背景图片

更换网站的背景图片。
编辑 themes/next/source/css/main.styl 文件。添加如下代码： 

1
2
3
4
5
6
7
8
// Customized Background
body {
    background-image: linear-gradient(rgba(0, 0, 0, 0.85), rgba(0, 0, 0, 0.85)), url("https://s2.loli.net/2025/06/25/LIZHY5o9aKwVviX.jpg");
    background-repeat: no-repeat;
    background-attachment: fixed;
    background-size: cover;
    background-position: center;
}

需要特别注意：如果使用了 Dark Reader 等浏览器插件，可能会导致自定义的 CSS 样式被覆盖，届时背景图片的样式可能不会正常显示。一些有关的问题在 Dark Reader 的 GitHub 主页上有相关的 issue 讨论，但仍未得到解决。

如果希望加上背景图随着鼠标移动而移动的效果，可以使用 parallax。忽略上面的代码，编辑 themes/next/source/css/main.styl 文件。添加如下代码： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
.parallax-background {
  width: 102%;
  height: 102%;
  /* z-index: -1; */
  background-image: linear-gradient(rgba(0, 0, 0, 0.85), rgba(0, 0, 0, 0.85)), url("https://s2.loli.net/2025/06/25/LIZHY5o9aKwVviX.jpg");
  background-attachment: fixed;
  background-size: cover;
  background-position: center;
  top: -1%;
  left: -1%;
  background-repeat: no-repeat;
  will-change: transform;
  transition: transform 0.1s ease-out;
  position: fixed;
}

然后，在 themes/next/layout/_layout.swig 文件中的 <body> 前添加如下 JavaScript 代码： 

1
2
3
4
5
6
7
8
9
10
11
12
13
<script>
/* parallax.js */
document.addEventListener('DOMContentLoaded', () => {
  const bg = document.getElementById('parallax-bg');
  const intensity = 16; // 控制移动幅度（值越大移动越明显）

  window.addEventListener('mousemove', (e) => {
    const x = (e.clientX / window.innerWidth - 0.5) * intensity;
    const y = (e.clientY / window.innerHeight - 0.5) * intensity;
    bg.style.transform = `translate(${-x}px, ${-y}px)`;
  });
});
</script>

最后在 themes/next/layout/_layout.swig 文件中的 <body> 标签内添加一个 div 元素作为背景图片容器： 

1
<div class="parallax-background" id="parallax-bg"></div>

更改页面元素透明度

为了使得背景图片不被侧边栏和文章页面遮挡，需要修改页面元素透明度。
编辑 themes/next/source/css/main.styl 文件。添加如下代码： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.header-inner { /* 分栏背景色 */
  background-color: rgba(51, 51, 51, 0.75);
}
.sidebar { /* 侧边栏背景色 */
  background-color: rgba(51, 51, 51, 0.0);
}
.sidebar-inner {
  background-color: rgba(51, 51, 51, 0.75);
  z-index: 1;
}
.post-block { /* 文章块背景色 */
  background-color: rgba(51, 51, 51, 0.75);
}
.search-popup { /* 搜索弹窗背景色 */
  opacity: 0.9;
}

注意：实际上应当尽量避免使用 opacity 属性，因为它会影响到子元素的透明度。这里使用 rgba 来设置颜色的透明度。

更改代码块样式

更改代码块的主题样式。
编辑 themes/next/_config.yml 文件中的 codeblock 配置。 

1
2
3
4
5
codeblock:
  highlight_theme: night
  copy_button:
    enable: true
    show_result: default

此外，在某些情况下，文本行内的内联代码块样式不会随 NexT 主题的亮色/暗色模式的更改而发生变化。此时需要手动调整内联代码块 <code> 的样式，这里只调整暗色模式下的代码块样式。
编辑 themes/next/source/css/main.styl 文件。添加如下代码： 

1
2
3
4
code {
  background: #1d1f21;
  color: #ffc5c5;
}

更改滚动条样式

更改右侧滚动条样式。
编辑 themes/next/source/css/main.styl 文件。添加如下代码： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Customized Scrollbar
::-webkit-scrollbar {
  width: 6px;
  height: 9px;
  background-color: #454545;
}
::-webkit-scrollbar-track {
  border-radius: 10px;
  background-color: #454545;
}
::-webkit-scrollbar-thumb {
  border-radius: 10px;
  background-color: #858585;
}
::-webkit-scrollbar-thumb:hover {
  background-color: #9e9e9e;
}

添加网站建立时间

在尾栏 footer 添加网站建立时间计时器。
编辑 themes/next/layout/_partials/footer.swig 文件。 

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
{%- if theme.footer.powered %}
  <div class="powered-by">
    {%- set next_site = 'https://theme-next.org' %}
    {%- if theme.scheme !== 'Gemini' %}
      {%- set next_site = 'https://' + theme.scheme | lower + '.theme-next.org' %}
    {%- endif %}
    {{- __('footer.powered', next_url('https://hexo.io', 'Hexo', {class: 'theme-link'}) + ' & ' + next_url(next_site, 'NexT.' + theme.scheme, {class: 'theme-link'})) }}
    <!-- 从这里开始添加代码 -->
    <span class="post-meta-divider">|</span>
    <span id="sitetime" class="post-meta-item"></span>
    <script>
        function siteTime(){
        window.setTimeout("siteTime()", 1000);
        var seconds = 1000;
        var minutes = seconds * 60;
        var hours = minutes * 60;
        var days = hours * 24;
        var years = days * 365;
        var today = new Date();
        var todayYear = today.getFullYear();
        var todayMonth = today.getMonth()+1;
        var todayDate = today.getDate();
        var todayHour = today.getHours();
        var todayMinute = today.getMinutes();
        var todaySecond = today.getSeconds();
        var t1 = Date.UTC(2021,09,01,00,00,00); // 网站建立时间
        var t2 = Date.UTC(todayYear,todayMonth,todayDate,todayHour,todayMinute,todaySecond);
        var diff = t2 - t1;
        var diffYears = Math.floor(diff/years);
        var diffDays = Math.floor((diff/days)-diffYears*365);
        var diffHours = Math.floor((diff-(diffYears*365+diffDays)*days)/hours);
        var diffMinutes = Math.floor((diff-(diffYears*365+diffDays)*days-diffHours*hours)/minutes);
        var diffSeconds = Math.floor((diff-(diffYears*365+diffDays)*days-diffHours*hours-diffMinutes*minutes)/seconds);
        document.getElementById("sitetime").innerHTML=" 本站已安全运行 "+diffYears+" years "+diffDays+" days "+diffHours+" hours "+diffMinutes+" mins "+diffSeconds+" secs";
        }
        siteTime();
    </script>
  </div>
{%- endif %}

Live2D

hexo-helper-live2d (不建议使用)

打开命令行，在 Blog 的根目录执行

1
npm install hexo-helper-live2d --save

编辑 _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
## Live2d
live2d:
  enable: true
  scriptFrom: local
  pluginRootPath: live2dw/
  pluginJsPath: lib/
  pluginModelPath: assets/
  tagMode: false
  debug: false
  model:
    use: model # 模型名称
    scale: 1
    hHeadPos: 0.5
    vHeadPos: 0.618
  display:
    superSample: 2
    width: 150
    height: 300
    position: right
    hOffset: 15
    vOffset: -20
  mobile:
    show: true
    scale: 0.5
  react:
    opacityDefault: 0.7
    opacityOnHover: 0.2

hexo-helper-live2d 自带部分公开的 Live2D 模型可供使用，具体可以在 https://github.com/xiazeyu/live2d-widget-models 查看和下载。
hexo-helper-live2d 也支持自定义模型文件。自定义的模型文件需要存放在 Blog 根目录的 live2d_models 目录中，并且也需要修改 _config.yml 配置中相应的模型名称，在生成静态文件时会根据配置进行读取。

live2d-widget

参考项目：在网页中添加Live2D看板娘
打开命令行，在 Blog 的根目录执行 

1
git clone git@github.com:stevenjoezhang/live2d-widget.git themes/next/source/live2d-widget

编辑 themes/next/source/live2d-widget/autoload.js 文件，修改 live2d_path 为部署后静态文件的相对路径： 

1
const live2d_path = "/live2d-widget/dist/";

编辑 themes/next/layout/_layout.swig 文件，在 <head> 和 <body> 之间添加如下代码： 

1
<script src="/live2d-widget/dist/autoload.js"></script>

编辑 themes/next/_config.yml 文件，添加 live2d 配置。 

1
2
live2d:
  enable: true

本站使用的是非默认的 Live2D 模型，在不使用 CDN 的情况下，一般将模型文件放置在 themes/next/source/live2d-widget/dist/assets 目录中。然后，修改 themes/next/source/live2d-widget/dist/waifu-tips.json 配置文件。

1
2
3
4
5
6
7
8
{
  ...
  "models": [{
    "name": "Hutao",
    "paths": ["/live2d-widget/dist/assets/hutaoyao-live2d/hutao.model3.json"],
    "message": "来自 Genshin Impact 的 胡桃 ～"
  }]
}

如果 Live2D 模型的位置未贴合页面最下方，可以通过修改 themes/next/source/live2d-widget/dist/waifu.css 样式文件中的属性，在 #waifu 标签中添加： 

1
2
3
#waifu {
    margin-bottom: -80px; /* 向下调整 Live2D 模型位置 */
}

手动调整 Live2D 的模型大小和方向，可以通过修改 #live2d 标签来实现： 

1
2
3
4
#live2d {
    /* cursor: grab; */ /* 取消光标移动到模型时的抓手样式 */
    transform: scale(-0.75, 0.75); /* 调整 Live2D 模型大小以及翻转 */
}

当然，这里并没有考虑到鼠标光标移动时与 Live2D 的 Canvas 的交互效果，这个问题以后有时间再解决。
另外，在使用 live2d-widget 在隐藏后再点击 waifu-toggle 可能会存在显示时图像消失的问题。
这个问题可以通过修改 themes/next/source/live2d-widget/waifu-tips.js 中的监听事件函数解决。
live2d-widget 项目经过重构后，waifu-tips.js 文件已经过混淆处理，一种简便的修改方式为：

  1. 在 waifu-tips.js 文件中 Ctrl+F 搜索并定位 3e3；
  2. 将位置左侧附近的 e.classList.add("waifu-hidden"); 注释掉。

以下是一些 Live2D 模型相关资源的链接：

Hexo 的使用相关

Hexo 常用命令

1
2
3
4
5
6
7
8
# 生成静态文件
hexo generate
# 生成静态文件并启动本地服务器
hexo server
# 生成静态文件并部署到远程服务器
hexo deploy
# 清除 Hexo 缓存
hexo clean

使用 SSH 进行部署

Hexo 默认的 git 使用 HTTPS 协议。由于 GitHub 的 HTTPS 443 端口由于网络连接原因经常出现连接超时的情况，因此建议为 GitHub 配置 SSH keys 方便今后部署到 GitHub Pages。
这里省略生成 SSH key、本地配置 SSH config 文件、在 GitHub 配置 SSH key 等步骤，只介绍 Hexo 配置 SSH 的步骤。
启用 SSH 需要安装hexo-deployer-git 插件。打开命令行，在 Blog 的根目录执行 

1
npm install hexo-deployer-git --save

之后编辑 _config.yml 文件。 

1
2
3
4
deploy:
  type: git # 使用 git 协议
  repo: git@github.com:scxs1388/scxs1388.github.io.git
  branch: page # 默认 main，如不是需要修改