1. 环境准备

  1. 安装git
  2. 安装nodejs
  3. 在cmd或git命令行中，执行以下命令安装hexo。
1
npm install -g hexo-cli

如果后续有些命令无法识别，可能说明安装完需要重启一下电脑。

2. 仓库创建

创建一个GitHub仓库，仓库名固定用户名.github.io。

仓库默认包含一个主分支main，再手动创建一个分支hexo。

  • main：存放编译后的静态页面，访问的博客也就是此处的内容。
  • hexo：存放编译前的源码文件，在此处进行文档编写，此分支用来在多设备同步内容。

在github仓库设置中，找到Pages，找到Build and deployment，选择从分支获取资源，分支选择main，然后保存。

3. 创建博客

创建一个空的文件夹Blog，并在此文件夹中打开git命令。

按顺序调用这三行命令。

1
2
3
4
5
hexo init  // 初始化，将本文件夹初始化为博客文件夹

hexo g  // 将源文件生成静态文件

hexo s  // 在本地启动服务

执行效果如下

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
XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/Blog
$ hexo init
INFO  Cloning hexo-starter https://github.com/hexojs/hexo-starter.git
INFO  Install dependencies
INFO  Start blogging with Hexo!

XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/Blog
$ hexo g
INFO  Validating config
INFO  Start processing
INFO  Files loaded in 368 ms
INFO  Generated: archives/index.html
INFO  Generated: index.html
INFO  Generated: archives/2025/08/index.html
INFO  Generated: fancybox/jquery.fancybox.min.css
INFO  Generated: css/style.css
INFO  Generated: js/script.js
INFO  Generated: archives/2025/index.html
INFO  Generated: fancybox/jquery.fancybox.min.js
INFO  Generated: js/jquery-3.6.4.min.js
INFO  Generated: 2025/08/29/hello-world/index.html
INFO  Generated: css/images/banner.jpg
INFO  11 files generated in 283 ms

XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/Blog
$ hexo s
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

执行完成后，将最后的地址http://localhost:4000/复制到浏览器即可看到默认的博客效果。

4. 修改主题

4.1 下载主题源码

在官网自带的主题https://hexo.io/themes/中找到一个喜欢的主题，这里选择NexT主题

按照github中提供的教程，将主题仓库clone到Blog/theme文件夹下。

1
2
3
4
5
6
7
8
9
XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/Blog
$ git clone https://github.com/next-theme/hexo-theme-next themes/next
Cloning into 'themes/next'...
remote: Enumerating objects: 7752, done.
remote: Counting objects: 100% (1052/1052), done.
remote: Compressing objects: 100% (209/209), done.
remote: Total 7752 (delta 926), reused 846 (delta 843), pack-reused 6700 (from 3)
Receiving objects: 100% (7752/7752), 1.64 MiB | 13.08 MiB/s, done.
Resolving deltas: 100% (4927/4927), done.

可以看到多出了Blog/theme/next这个文件夹。

4.2 主题美化

4.2.1 主题基本信息

修改主题标志，打开Blog/_config.yml这个文件，找到最下面的theme字段，修改为目标主题next，然后保存。

1
2
3
4
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: next

语言修改，还是这个文件，找到language: en，修改为中文。

1
language: zh-CN

网站显示的基本信息如下：

1
2
3
4
5
6
7
8
# Site
title: Blog
subtitle: '攻城狮装备搭建日记'
description: '身体和心灵总有一个在路上'
keywords:
author: Haozi
language: zh-CN
timezone: ''

4.2.2 布局信息美化

这个主题内部还有很多其他的配置项，保存在Blog\themes\next\_config.yml，但是NexT文档不推荐直接修改此文件，建议修改方式如下：

将主题文件夹下默认的配置文件Blog\themes\next复制到项目根目录并重命名为Blog\_config.next.yml

1
cp themes/next/_config.yml _config.next.yml

主题布局选择

主题内部还分为四种不同的主题布局，配置方式如下：

将Blog\_config.next.yml文件中的如下字段选择如下：

1
2
3
4
5
# Schemes
# scheme: Muse
#scheme: Mist
#scheme: Pisces
scheme: Gemini

4.2.3 分类和标签功能

Blog\_config.next.yml文件下，找到以下字段，根据需要打开对应的菜单项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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

# Enable / Disable menu icons / item badges.
menu_settings:
  icons: true
  badges: false

其中使用的菜单图标都是来自于Font Awesome，可以在这个网站找到自己喜欢的图标后，把图标名称写在 || 后面即可。

此时，当我们在首页点击 标签 或 分类 时，会报 404 ，这是因为我们还没有创建对应的文件夹，所以报 404 找不到。因此，需要在本地创建标签和分类文件夹。

1
2
hexo new page 'tags' # 创建tags子目录
hexo new page 'categories' # 创建categories子目录

执行效果如下，本地会多出来两个文件夹。

1
2
3
4
5
6
7
8
9
XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/imhaozi.github.io (hexo)
$ hexo new page 'tags'
INFO  Validating config
INFO  Created: ~\Desktop\imhaozi.github.io\source\tags\index.md

XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/imhaozi.github.io (hexo)
$ hexo new page 'categories'
INFO  Validating config
INFO  Created: ~\Desktop\imhaozi.github.io\source\categories\index.md

此时如果重新发布网站之后，页面不会报错，但是还不能自动检索文章，需要在刚才生成的文件夹中的index.md 中增加对应的 type 属性。

添加完之后如下：

categories下的index

1
2
3
4
5
---
title: categories
date: 2025-09-01 15:44:04
type: categories
---

tags下的index

1
2
3
4
5
---
title: tags
date: 2025-09-01 15:43:56
type: tags
---

新发布的文章也需要加上对应的标签和主题才可以被检索到，比如本文章。

1
2
3
4
5
6
7
8
9
---
title: 博客搭建指南
date: 2025-08-29 18:49:27
tags:
  - blog
  - hexo
categories:
  - 工具
---

上面这个文章，属于工具类别，标签加了两个hexo、blog.

4.2.4 首页不显示全文

网站首页默认会将文章全文显示，但是一般都不是我们想看的内容，可以选择把文章都只显示一个概要，然后可以点进去再看全文。

只需要在文章头部添加description字段即可。

1
2
3
4
5
6
7
---
title: 博客搭建指南
date: 2025-08-29 18:49:27
tags: [hexo,blog]
categories: 工具
description: 记录搭建博客和美化主题的过程
---

4.2.5 文章搜索功能

安装插件

1
2
npm install hexo-generator-search  --save
npm install hexo-generator-searchdb --save

安装效果如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/imhaozi.github.io (hexo)
$ npm install hexo-generator-search  --save

added 1 package, and audited 238 packages in 2s

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

found 0 vulnerabilities

XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/imhaozi.github.io (hexo)
$ npm install hexo-generator-searchdb --save

added 1 package, and audited 239 packages in 2s

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

found 0 vulnerabilities

Blog\_config.next.yml文件下，添加如下字段（默认是没有这个字段的）

1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

然后将以下字段修改使能

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

4.2.6 隐藏底部强力驱动

Blog\_config.next.yml文件下

1
2
# Powered by Hexo & NexT
powered: false

4.2.7 目录自己编号

主题默认会给文章目录加编号，如果我们自己已经加了编号了就会重复，需要关掉此功能。

Blog\_config.next.yml文件下

1
2
3
4
toc:
  enable: true
  # Automatically add list number to toc.
  number: false

4.2.8 文章默认格式

在 Hexo 根目录下 修改 scaffolds/post.md

1
2
3
4
5
title: {{ title }}
date: {{ date }}
tags: [tag1,tag2]
categories: [类别]
description: null

4.2.9 代码块格式和复制按钮

Blog\_config.next.yml文件下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
codeblock:
  # Code Highlight theme
  # All available themes: https://theme-next.js.org/highlight/
  theme:
    light: default
    dark: stackoverflow-dark
  prism:
    light: prism
    dark: prism-dark
  # Add copy button on codeblock
  copy_button:
    enable: true
    # Available values: default | flat | mac
    style:
  # Fold code block
  fold:
    enable: true
    height: 500
  # Display language name
  language: true

4.2.10 文章阅读进度

Blog\_config.next.yml文件下

1
2
3
4
5
6
7
8
9
10
# Reading progress bar
reading_progress:
  enable: true
  # Available values: left | right
  start_at: left
  # Available values: top | bottom
  position: top
  reversed: false
  color: "#37c6c0"
  height: 3px

4.2.11 文章和图片单独创建文件夹

Blog/_config.yml这个文件

1
post_asset_folder: true

4.3 重新运行

执行下面三行命令，重新生成静态文件。

1
2
3
hexo clean
hexo g
hexo s

执行完成后，将最后的地址http://localhost:4000/复制到浏览器即可看到修改后的主题博客效果。

5. github推送

打开Blog/_config.yml这个文件，找到最下面的deploy字段，添加如下信息，然后保存。其中repo为仓库的链接。

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: https://github.com/imhaozi/imhaozi.github.io.git
  branch: main

安装git部署插件

1
2
3
4
5
6
7
8
9
XCHARGE-2024Q2-LT003@LAPTOP-F010DA3K MINGW64 ~/Desktop/Blog
$ npm install hexo-deployer-git --save

added 10 packages, and audited 237 packages in 3s

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

found 0 vulnerabilities

重新生成界面并推送到远端。

1
2
3
hexo clean
hexo g
hexo d // 部署到服务上

完成后在浏览器中访问用户名.github.io即可访问博客内容。

6. 多端同步

本机操作：

  1. 将远端仓库克隆到本地，并切换到hexo分支。并将此分支下的文件都删掉，仅留下.git
  2. 将创建的Blog文件夹中的内容全部复制到，hexo分支的仓库文件夹，并删去.deploy_git文件夹
  3. 如果你在Blog/themes文件夹下 clone 过其它主题文件，把其中的 .git文件夹删除掉
  4. 将hexo分支的内容推送到远端

异地操作：

  1. 首次创建博客的电脑需要先将首次创建完成的博客源码推送到远端（上面的步骤）
  2. 本机下载已经上传到远端的源码
  3. 本机安装环境npm install hexo-cli -g、npm install hexo-deployer-git --save（如果创建的博客还需要其他的就分别安装）
  4. 在本机的hexo分支上继续写博客，写完之后生成并推送
  5. 博客推送完成后，记得把源码推送到远端。

7. 博客图片显示

安装图片插件

1
npm install https://github.com/CodeFalling/hexo-asset-image --save

修改配置，打开Blog/_config.yml这个文件，找到最下面的post_asset_folder字段

1
post_asset_folder: true

后面新建文章的时候，会自动创建同文件名的文件夹（或者手动创建md文件和文件夹），图片都可以放到这个文件夹下。

插入图片的时候，采用如下形式。

1
![CAN接线方式](./canopen/CAN接线方式.jpg)
许可协议

本文由 imhaozi 编写，采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。