使用Hexo在Github上搭建个人Blog笔记

发表于 分类于
使用Hexo在Github上搭建个人Blog笔记，包含Hexo环境搭建及安装、Hexo参数配置及Next主题页面配置等。

1.安装node.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
>> # 1.源码下载
>> wget https://nodejs.org/dist/v16.17.0/node-v16.17.0-linux-x64.tar.xz
# 2.源码解压
>> tar -xvJf node-v16.17.0-linux-x64.tar.xz
>> mv node-v16.17.0-linux-x64 node
# 3.获取node的路径
>> cd node/bin && pwd
/home/mirror/software/node/bin
# 4.将当前路径添加到系统环境变量中
# ~/.bashrc 或 ~/.zshrc
>> vim ~/.zshrc
export NODE=/home/mirror/software/node/bin
export PATH=$PATH:$NODE
# 5.刷新系统环境变量
>> source ~/.zshrc
# 6.查看node和npm版本
>> node -v
v16.17.0
>> npm -v
8.15.0

2.初始化Hexo博客

2.1 安装Hexo包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 1.安装Hexo脚手架
>> npm install -g hexo-cli@4.3.0
# 2.查看Hexo版本
>> hexo -v
hexo-cli: 4.3.0
os: linux 6.6.87.2-microsoft-standard-WSL2 Ubuntu 20.04.6 LTS (Focal Fossa)
node: 16.17.0
v8: 9.4.146.26-node.22
uv: 1.43.0
zlib: 1.2.11
brotli: 1.0.9
ares: 1.18.1
modules: 93
nghttp2: 1.47.0
napi: 8
llhttp: 6.0.7
openssl: 1.1.1q+quic
cldr: 41.0
icu: 71.1
tz: 2022a
unicode: 14.0
ngtcp2: 0.1.0-DEV
nghttp3: 0.1.0-DEV

2.2 初始化Hexo博客

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
# 1.创建目录存放博客源码
>> mkdir hexo-blog
# 2.初始化hexo项目
>> cd hexo-blog && hexo init
# 3.安装项目依赖
>> npm install
# 4.降级hexo
>> npm install hexo@6.3.0 --save
# 5.本地预览
>> hexo clean && hexo generate && hexo server
INFO  Validating config
INFO  Validating config
INFO  Start processing
INFO  Files loaded in 126 ms
INFO  Generated: archives/index.html
INFO  Generated: index.html
INFO  Generated: archives/2026/01/index.html
INFO  Generated: js/script.js
INFO  Generated: fancybox/jquery.fancybox.min.css
INFO  Generated: css/style.css
INFO  Generated: archives/2026/index.html
INFO  Generated: fancybox/jquery.fancybox.min.js
INFO  Generated: js/jquery-3.6.4.min.js
INFO  Generated: 2026/01/07/hello-world/index.html
INFO  Generated: css/images/banner.jpg
INFO  11 files generated in 188 ms
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

3.创建github page仓库

  • （1）登录github，创建仓库，仓库名必须严格遵循格式：你的github用户名.github.io，例如，我的用户名MirrorYuChen，仓库名就是MirrorYuChen.github.io。
  • （2）账户添加SSH公钥，避免每次部署都需要输入账号密码。
  • （3）验证SSH连接：出现Hi 你的用户名！You've successfully authenticated, but GitHub does not provide shell access.即成功：
1
2
>> ssh -T git@github.com
Hi MirrorYuChen! You've successfully authenticated, but GitHub does not provide shell access.

4.配置Hexo部署参数

  • （1）打开hexp-blog文件夹下的_config.yml文件，找到deploy部分，修改为以下内容：
1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: git@github.com:你的GitHub用户名/你的GitHub用户名.github.io.git
  branch: main  # 注意：GitHub 默认分支是 main（旧版是 master），根据自己的仓库分支改

 例如：

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: git@github.com:MirrorYuChen/MirrorYuChen.github.io.git
  branch: main
  • （2）安装Hexo的Git部署插件：
1
>> npm install hexo-deployer-git --save
  • （3）部署到Github Pages
1
>> hexo clean && hexo generate && hexo deploy  # 简写：hexo cl && hexo g && hexo d

5.日常使用

  • （1）新建文章：hexo new "文章标题"，会在source/_posts下生成Markdown文件，编辑该文件即可写文章；
  • （2）更换主题：下载Hexo主题（如，Next、Butterfly），放在themes文件夹，修改_config.yml中的theme:主题名，重新部署即可；
1
2
3
4
5
6
7
8
9
10
11
# 1.下载主题: butterfly和next
>> cd hexo-blog &&  git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
>> npm install hexo-theme-next@latest
# 2.安装默认Pug渲染器
>> npm install hexo-renderer-pug --save
# 3.配置主题
>> vim _config.yml
# (1) butterfly主题
theme: butterfly
# (2) next主题
theme: next
  • （3）本地修改后，重新部署：重复执行hexo cl && hexo g && hexo d。

6.新增并配置分类

6.1 创建分类页面

  • （1）进入hexo-blog目录，打开终端执行命令：
1
2
3
>> hexo new page "工具使用"
INFO  Validating config
INFO  Created: ~/hexo-blog/source/categories/index.md
  • （2）编辑source/categories/index.md文件：必须添加type:"categories"，否则分类页面不生效：
1
2
3
4
5
---
title: 工具使用
date: 2026-01-07 14:39:42
type: "categories"
---

6.2 给文章分配分类

  • （1）方式一：新建文章时直接指定：
1
>> hexo new "使用Hexo在github上搭建个人博客" --category "工具使用"
  • （2）方式二：直接修改文章文件：对应文章头部---之间添加categories字段，如：
1
2
3
4
title: 使用Hexo在github上搭建个人博客
categories: ["工具使用"]
date: 2026-01-07 14:54:48
tags:

7.插入图片

7.1 全局资源文件夹

  • （1）在source目录下创建一个名为images的文件夹（名称可自定义）；
  • （2）将需要插入的图片放入该文件夹，如：source/images/hexo.jpg
  • （3）插入图片：![描述](/images/hexo.jpg)
    hexo

7.2 文章资源文件夹

  • （1）修改配置_config.yml，启用文章资源文件夹：
1
post_asset_folder: true
  • （2）新建一篇文章：
1
2
3
>> hexo new "常用git命令学习笔记" --category "工具 使用"
INFO  Validating config
INFO  Created: ~/hexo-blog/source/_posts/常用git命令学习笔记.md

 会自动在source\_posts下创建一个和文章名同名的文件夹，将图片放入该文件夹，如，hexo.jpg

  • （3）插入图片
1
2
3
4
5
6
7
# 方法1.markdown语法
## 1.1 安装对应插件
>> npm install https://github.com/CodeFalling/hexo-asset-image.git --save
## 1.2 使用markdown语法
![](hexo.jpg)
# 方法2.使用hexo原生支持方式
{% asset_img hexo.jpg 可选的图片描述 %}

8.问题处理

  • （1）大纲出现重复序号：修改主题插件的toc配置，node_modules/hexo-theme-next/_config.yml，toc字段改为如下内容：
1
2
3
4
5
6
7
8
9
10
11
12
# Table of Contents in the Sidebar
# Front-matter variable (nonsupport wrap expand_all).
toc:
  enable: true
  # Automatically add list number to toc.
  number: false
  # If true, all words will placed on next lines if header width longer then sidebar width.
  wrap: false
  # If true, all level of TOC in a post will be displayed, rather than the activated part of it.
  expand_all: false
  # Maximum heading depth of generated toc.
  max_depth: 3
  • （2）创建的ReadMe.md文件会被覆盖掉
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1.修改source\_config.yml文件
skip_render: ReadMe.md
# 2.在source文件夹下创建ReadMe.md文件，并添加如下内容：
## MirrorYuChen.github.io
* Author: chenjingyu
* Date: 20260107

## 1.项目描述
* 基于Hexo搭建的个人博客系统，并部署在github.io上；
* [个人博客地址](https://mirroryuchen.github.io/)
* **如果您对我的博客内容有疑惑或质疑的地方，请在下方评论区留言，或邮件给我，共同学习进步。**
* **邮箱：2458006366@qq.com**

## 2.更新日志
|日期|更新内容|
|--|--|
|20260107|1.添加使用Hexo在github上搭建个人博客笔记；|
  • （3）无法访问categories和tags：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1.创建categories页
>> hexo new page categories 
INFO  Validating config
INFO  Created: ~/hexo-blog/source/categories/index.md
# 2.编辑categories页面配置
>> vim source/categories/index.md
# 添加如下内容：
type: "categories"
layout: "categories"
# 3.创建tags页
>> hexo new page tags
INFO  Validating config
INFO  Created: ~/hexo-blog/source/tags/index.md
# 4.编辑tags页配置
>> vim source/tags/index.md
# 添加如下内容：
type: "tags"
layout: "tags"
  • （4）代码一键复制功能
1
2
3
# 1.在node_modules/hexo-theme-next/_config.yml文件中，将
copy_button:
    enable: true   # 这里设置成true就行了

9.主题配置

9.1 打开菜单选项

 查询node_modules/hexo-theme-next/_config.yml或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
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  schedule: /schedule/ || fa fa-calendar
  #sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat

9.2 创建菜单内容

 home和archives是已有的，无需额外创建页面，about，tags，categories和schedule需要单独创建页面才能预览：

  • （1）创建about页：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 1.创建页面about页
>> hexo new page about
# 2.添加about页内容：
>> vim source/about/index.md
# 修改为如下内容，具体描述可以按需修改：
---
title: About
date: 2026-01-09 19:54:50
type: "about"
---

# 关于我的博客
这是一个基于Hexo + Next主题搭建的静态个人博客，用于分享技术笔记和生活感悟。

## 1.个人简介
- 昵称：MirrorYuChen
- 擅长技术：C++/C，Python
- 联系方式：2458006366@qq.com

## 2.博客说明
本博客搭建于2026年，使用Hexo框架生成，部署在GitHub Pages上，主题采用Next。
  • （2）创建categories页：
1
2
3
4
5
6
7
8
9
10
11
# 1.创建categories页
>> hexo new page categories
# 2.修改categories页内容
>> vim source/categories/index.md
# 修改为如下内容：
---
title: categories
date: 2026-01-09 18:32:40
type: "categories"
layout: "categories"
---
  • （3）创建tags页：
1
2
3
4
5
6
7
8
9
10
11
# 1.创建categories页
>> hexo new page tags
# 2.修改categories页内容
>> vim source/tags/index.md
# 修改为如下内容：
---
title: tags
date: 2026-01-09 18:38:03
type: "tags"
layout: "tags"
---
  • （4）创建schedule页：
1
2
3
4
5
6
7
8
# 2.添加about页内容：
>> vim source/schedule/index.md
# 修改为如下内容，具体描述可以按需修改：
---
title: Schedule
date: 2026-01-09 19:54:50
type: "schedule"
---

 这样就配置好了相关菜单页。

9.3 个性化配置

  • （1）设置个人形象

 首先，将要设置的图像放置到node_modules/hexo-theme-next/source/images或 themes/next/source/images下；然后，修改node_modules/hexo-theme-next/_config.yml或themes/next/_config.yml文件的avatar:字段：

1
2
3
4
5
6
7
8
# Sidebar Avatar
avatar:
  # Replace the default image and set the url here.
  url: /images/avatar.png
  # If true, the avatar will be displayed in circle.
  rounded: true
  # If true, the avatar will be rotated with the cursor.
  rotated: false
  • （2）设置社交链接

 修改node_modules/hexo-theme-next/_config.yml或themes/next/_config.yml文件的social字段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Social Links
# Usage: `Key: permalink || icon`
# Key is the link label showing to end users.
# Value before `||` delimiter is the target permalink, value after `||` delimiter is the name of Font Awesome icon.
social:
  GitHub: https://github.com/MirrorYuChen || fab fa-github
  E-Mail: 2458006366@qq.com || fa fa-envelope
  #Weibo: https://weibo.com/yourname || fab fa-weibo
  #Twitter: https://twitter.com/yourname || fab fa-twitter
  #FB Page: https://www.facebook.com/yourname || fab fa-facebook
  #StackOverflow: https://stackoverflow.com/yourname || fab fa-stack-overflow
  #YouTube: https://youtube.com/yourname || fab fa-youtube
  #Instagram: https://instagram.com/yourname || fab fa-instagram
  #Skype: skype:yourname?call|chat || fab fa-skype
  • （3）边栏默认打开

 修改主题的配置_config.yml文件，查找sidebar:，修改为如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
sidebar:
  # Sidebar position. Available values: left | right
  position: left

  # Sidebar width.
  # Applicable to Muse | Mist and mobile of Pisces | Gemini.
  width_expanded: 320
  # Applicable to desktop of Pisces | Gemini.
  width_dual_column: 240

  # Sidebar display.
  # Applicable to Muse | Mist and mobile of Pisces | Gemini.
  # Available values:
  #  - post    expand on posts automatically. Default.
  #  - always  expand for all pages automatically.
  #  - hide    expand only when click on the sidebar toggle icon.
  #  - remove  totally remove sidebar including sidebar toggle.
  display: always    # post 改为always

  # Sidebar padding in pixels.
  padding: 18
  # Sidebar offset from top menubar in pixels (only for Pisces | Gemini).
  offset: 12

 最后就可以得到如下页面：

hexo_next

10.本地搜索

  • （1）安装插件hexo-generator-searchdb
1
>> npm install hexo-generator-searchdb --save
  • （2）修改主题配置：查询node_modules/hexo-theme-next/_config.yml或themes/next/_config.yml里面menu:字段，将下面的注释都打开：
1
2
3
4
5
6
7
8
9
10
# Local Search
# Dependencies: https://github.com/next-theme/hexo-generator-searchdb
local_search:
  enable: true
  # Show top n results per article, show all results by setting to -1
  top_n_per_article: 1
  # Unescape html strings to the readable one.
  unescape: false
  # Preload the search data when the page loads.
  preload: false

参考资料