使用Hexo在github上搭建个人博客

发表于 更新于 分类于
使用Hexo在github上搭建个人博客学习笔记

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就行了

参考资料：