hexo 博客搭建部署

Posted on In , Views: Word count in article: 7.8k Reading time ≈ 7 mins.
使用 Github Page 来搭建部署自己的博客，踩坑并解决一些bug

hexo 本地搭建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
D:\Developer>hexo init github_blog
INFO  Cloning hexo-starter https://github.com/hexojs/hexo-starter.git
INFO  Install dependencies
INFO  Start blogging with Hexo!

D:\Developer>cd github_blog

D:\Developer\github_blog>hexo g
INFO  Validating config
INFO  Start processing
INFO  Files loaded in 175 ms
INFO  Generated: archives/index.html
INFO  Generated: index.html
INFO  Generated: css/style.css
...
INFO  Generated: css/images/banner.jpg
INFO  11 files generated in 163 ms

D:\Developer\github_blog>hexo server
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.
1
2
3
4
hexo new "my new post"  # Create a new post
hexo generate    # Generate static files
hexo server  # Run server
hexo deploy  # Deploy to remote sites

部署到 github

1
2
3
4
npm install hexo-deployer-git --save
hexo clean  # 清除旧的生成文件和缓存。
hexo g  # 根据内容生成新的静态页面。
hexo deploy  # 将生成的页面部署到服务器或 GitHub Pages。

next 主题安装和配置

从 https://github.com/iissnan/hexo-theme-next fork 一份到自己的 github 上，为了方便跟踪改了哪些配置，再克隆到 github_blod 目录中。

1
D:\Developer\github_blog>git clone git@github.com:zypdominate/hexo-theme-next.git themes/next

修改 _config.yaml，

1
2
3
# Extensions
# theme: landscape
theme: next

重新启动服务，出现一个报错：

1
2
3
{% extends '_layout.swig' %} {% import '_macro/post.swig' as post_template %} {% import '_macro/sidebar.swig' as sidebar_template %} {% block title %}{{ config.title }}{% if theme.index_with_subtitle and config.subtitle %} - {{config.subtitle }}{% endif %}{% endblock %} {% block page_class %} {% if is_home() %}page-home{% endif -%} {% endblock %} {% block content %}
{% for post in page.posts %} {{ post_template.render(post, true) }} {% endfor %}
{% include '_partials/pagination.swig' %} {% endblock %} {% block sidebar %} {{ sidebar_template.render(false) }} {% endblock %}

解决：npm i hexo-renderer-swig

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
D:\Developer\github_blog>npm i hexo-renderer-swig
npm warn deprecated hexo-renderer-swig@2.0.0: hexo-renderer-swig has been deprecated. Please use other template engines. (e.g. nunjucks https://github.com/hexojs/hexo-renderer-nunjucks)
npm warn deprecated swig-templates@2.0.3: unmaintained

added 28 packages, and audited 256 packages in 5m

23 packages are looking for funding
  run `npm fund` for details

6 vulnerabilities (2 low, 1 high, 3 critical)

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

标签和分类

设置菜单栏，修改 _config.yaml

1
2
3
4
5
6
menu:
  home: /
  categories: /categories/
  tags: /tags/
  archives: /archives/
  about: /about/

创建页面：categories，tages，about。在此之前，如果没有创建，点击主页上的这些菜单，会出现 Cannot GET /categories/ 这样的报错。

1
2
3
4
5
6
7
8
9
10
11
D:\Developer\github_blog>hexo new page categories
INFO  Validating config
INFO  Created: D:\Developer\github_blog\source\categories\index.md

D:\Developer\github_blog>hexo new page tags
INFO  Validating config
INFO  Created: D:\Developer\github_blog\source\tags\index.md

D:\Developer\github_blog>hexo new page about
INFO  Validating config
INFO  Created: D:\Developer\github_blog\source\about\index.md

分别修改对应的index.md文件

1
2
3
4
5
6
---
title: categories
date: 2018-07-01 23:37:24
type: "categories"

---
1
2
3
title: tages
date: 2018-07-01 23:33:14
type: "tags"

一篇文章多个分类

在很多情况下，我们希望在 Hexo 中写的一篇文章能够同时属于多个分类，例如我写一篇 [《Python自动化测试》]，我既想将它放在 [Python] 这个分类中，又想将它放入 [自动化测试] 这个分类。

子分类

下面的分类会将该分章放到 Python/Automation这个分类下

1
2
3
categories:
  - Python
  - Automation

或者

1
categories: [Python, Automation]

多个分类

如果要求是将文章同时分到多个不同的分类中呢，应该这样：

1
2
3
categories:
  -[Python]
  -[Automation]

这样，就可以将上面的文章分类到 Python 和 Automation 这两个不同的目录中了。

扩展一下，如果我们将其分类到 Python/Servlet 和 Programming 两个不同的目录下，我们应该如下写：

1
2
3
categories:
  -[Python, Automation]
  -[Programming]

网站描述

1
2
3
4
5
6
7
8
# Site
title: Magnolia的博客
subtitle: '持续成长'
description: 'Just do it'
keywords:
author: Magnolia
language: en
timezone: Asia/Nanjing

头像

将图片放到 source/images 里面

1
2
# Sidebar Avatar
avatar: /images/avatar.jpg

侧边栏社交链接

1
2
3
4
5
social:
  CSDN: https://blog.csdn.net/xxxx || cndn
  Gitee: https://gitee.com/xxxx || gitee
  GitHub: https://github.com/xxxx || github
  E-Mail: mailto:xxxx@gmail.com || envelope

字数统计和阅读时长

安装插件

1
npm install hexo-symbols-count-time --save

修改配置

1
2
3
4
5
6
7
8
9
10
11
12
13
symbols_count_time:
  #文章内是否显示
  symbols: true
  time: true
  # 网页底部是否显示
  total_symbols: true
  total_time: true
  separated_meta: true
  item_text_post: true
  item_text_total: false
  awl: 4
  wpm: 275
  suffix: mins.

遇到的报错问题并解决

文章摘要显示数字

解决：

在文章的 front-matter 中添加 description: xxx，description 的内容就是被显示在首页上，其他的不显示。

或者在文件内容中加入截断，<!--more-->，在这之后的内容就不会显示。

分页的前一页下一页显示不对

将以下内容：

1
2
3
4
5
6
7
8
9
10
11
{% if page.prev or page.next %}
  <nav class="pagination">
    {{
      paginator({
        prev_text: '<i class="fa fa-angle-left"></i>',
        next_text: '<i class="fa fa-angle-right"></i>',
        mid_size: 1
      })
    }}
  </nav>
{% endif %}

改为：

1
2
3
4
5
6
7
8
9
10
11
12
{% if page.prev or page.next %}
  <nav class="pagination">
    {{
      paginator({
        prev_text: '<i class="fa fa-angle-left" aria-label="' + __('accessibility.prev_page') + '"></i>',
        next_text: '<i class="fa fa-angle-right" aria-label="' + __('accessibility.next_page') + '"></i>',
        mid_size: 1,
        escape: false
      })
    }}
  </nav>
{% endif %}

部署报错

1
2
3
4
5
6
7
fatal: unable to access 'https://github.com/zypdominate/zypdominate.github.io.git/': Failed to connect to github.com port 443 after 21084 ms: Could not connect to server
FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
Error: Spawn failed
    at ChildProcess.<anonymous> (D:\Developer\github_blog\node_modules\hexo-deployer-git\node_modules\hexo-util\lib\spawn.js:51:21)
    at ChildProcess.emit (node:events:519:28)
    at cp.emit (D:\Developer\github_blog\node_modules\cross-spawn\lib\enoent.js:34:29)
    at ChildProcess._handle.onexit (node:internal/child_process:294:12)

重新执行了一遍：

1
2
3
4
npm install hexo-deployer-git --save
hexo clean  # 清除旧的生成文件和缓存。
hexo g  # 根据内容生成新的静态页面。
hexo d  # 将生成的页面部署到服务器或 GitHub Pages。

修改 Hosts 文件（解决 DNS 污染）：
在 C:\Windows\System32\drivers\etc\hosts 中添加：

1
140.82.112.4 github.com

点击目录无法跳转

在文章中，点击左侧的含中文的目录，没法跳转到对应的标题。

解决：

1
2
3
4
5
6
7
8
9
10
11
12
// Handle the clicking of TOC links
$('.post-toc a').on('click', function (e) {
  e.preventDefault();
  var targetId = decodeURIComponent($(this).attr('href'));
  var target = $(targetId);

  if (target.length) {
    $('html, body').animate({
      scrollTop: target.offset().top
    }, 500);
  }
});
  • 等待文档加载完成
  • 为所有目录链接添加点击事件监听器
  • 阻止默认的跳转行为
  • 解码链接中的中文字符
  • 平滑滚动到目标位置

清除浏览器缓存并重新生成静态文件，hexo clean，hexo generate

侧边栏目录带有编号问题

默认情况下，Next 主题会给侧边栏的目录自动编号。

文章中标题本身没有 1. 2. 3. 这样的有序列表前的数字，但是启动服务后，加载出来的文件的侧边栏目录中带有 1. 2. 3. 4.，如果原来标题就有1.2.3，那么出现 1.1 2.2 3.3 这样的显示，很难看。

解决：打开 themes/next/_config.yml 文件，找到 toc 相关的配置部分，修改以下配置：

1
2
3
4
5
6
7
toc:
  enable: true
  # 将 number 设置为 false 来关闭自动编号
  number: false  
  wrap: false
  expand_all: false
  max_depth: 6

主要是将 number: true 改为 number: false，这样就能关闭目录的自动编号功能。侧边栏的目录就不会自动添加数字编号了，会保持和文章标题一致的格式。

点击多级标题无法展开

询问 Claude，问题出在目录的 HTML 结构上，给 Claude 我博客文章点击目录后的结构 html，针对性地修改 JavaScript 代码。发现目录结构使用了 nav-child 类来表示子目录，于是修改如下后，解决问题。

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
$(document).ready(function() {
  // 处理目录点击展开/折叠
  $('.post-toc .nav-item').on('click', function(e) {
    e.stopPropagation(); // 阻止事件冒泡
    
    var $this = $(this);
    var $subNav = $this.children('.nav-child');
    
    // 如果有子目录
    if ($subNav.length > 0) {
      e.preventDefault(); // 阻止默认跳转
      $subNav.slideToggle(200);
      $this.toggleClass('expanded');
    }
  });
  
  // 初始展开当前活动的目录项
  function expandActiveNav() {
    var $activeItem = $('.post-toc .active-current').parent();
    $activeItem.parents('.nav-child').show();
    $activeItem.parents('.nav-item').addClass('expanded');
  }
  
  // 首次加载时展开
  expandActiveNav();
  
  // 滚动时保持展开状态
  $(window).on('activate.bs.scrollspy', function() {
    expandActiveNav();
  });
});

gif 图片没有加载

配置 _config.yml

1
post_asset_folder: true

修改图片命令，去除图片中的空格。