前言

欢迎来到我的世界！这里是 Mr. O。你是否也有过这样的想法：拥有一个属于自己的博客，记录生活的点滴、分享自己的经验或者展示你的专业技能？

其实，搭建一个个人博客并不像想象的那么复杂。借助 GitHub 提供的免费托管服务，以及功能强大、简单易用的 Hexo 静态博客框架，我么可以轻松打造一个属于自己的博客平台。而且，这个过程完全免费！

在本文中，我将带你一步步了解如何利用 GitHub Pages 和 Hexo 快速部署一个美观、实用的个人博客，让你的思想在网络世界自由驰骋。

让我们开始吧！

Hexo

Hexo 是一个快速、简洁且高效的博客框架，支持丰富的 主题 ，我们只需要使用 Markdown 语法编写文章，Hexo 将为我们生成网站的文件。

GitHub

GitHub 是全球最大的代码托管网站和开源社区，我们可以使用 GitHub 免费的 Pages 服务托管我们的博客。

如果你还没有 Github 账户，可以免费注册一个： https://github.com/signup

准备工作

拥有了 GitHub 账户之后，我们需要在电脑上安装下面的软件

VS Code 安装后可以点击左侧扩展，搜索 简体中文 安装语言包，点击 Install 后点击右下角 Change Language and Restart 重启
image

安装完成后打开终端程序，可以通过查询版本命令确认是否完成安装。

1
2
3
4
5
> npm -v
10.9.2

> git -v
git version 2.47.0

如何打开终端：

使用 VS Code ，可以按 Ctrl + ` (Esc 下面的按键) 快捷键在底部打开终端程序。
也可以使用菜单 终端 > 打开终端

VSCode 终端执行命令报错？

设置默认终端为 cmd 即可

image image

然后关闭 VS Code 重新打开

安装 Hexo

我们需要在终端内使用 npm 命令安装我们的 Hexo 博客：

1
npm install hexo-cli -g

执行结束后，再执行 hexo -v 命令，如果成功输出版本信息则表示安装成功： 

1
2
3
4
5
6
> hexo -v
hexo-cli: 4.3.2
os: darwin 24.1.0 15.1.1
node: 23.3.0
acorn: 8.14.0
# ...

然后创建一个空文件夹用于存放博客文件，创建后使用 VS Code 选择 打开文件夹 打开它，再打开 VS Code 的终端，依次运行下面的命令

初始化博客

1
hexo init

此时可以查看 VS Code 侧边栏，已自动生成了很多文件，一般我们只需要关注 source 中的内容，其中 _posts 是我们存放博客文章的地方。
VS Code Sidebar

预览博客

使用 hexo s 命令可以在电脑本地预览网站效果。

1
2
3
4
5
> hexo s
# 如果输出下面内容就表示成功了
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

然后我们就可以打开浏览器，访问 http://localhost:4000/ 即可查看网站预览。

Hexo Preview

hexo s 是 hexo server 的简短形式，更加方便

VS Code 内 Windows 按住 Ctrl , macOS 按住 Commond⌘ 点击终端内链接可以快速打开

不需要时后按 Ctrl + C 结束进程

设置博客信息

我们需要编辑根目录下的 _config.yml 文件设置我们自己的站点信息

_config.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Site
## title 是站点的名称
title: 'O’s World'
## subtitle 副标题，一般会显示在站点名称的下面
subtitle: 'Mr. O 的分享小站，分享有趣的事情'
## description 描述站点的内容
description: '探索互联网世界，分享实用教程与精彩内容，发现更多有趣之处。'
## keywords 是站点的关键词，用于搜索引擎的 SEO 优化，填写几个单词，告诉搜索引擎一些信息。
keywords: 
## author 是作者的名称，一般使用自己的昵称
author: Mr. O
## 站点的语言
language: zh-CN
## timezone 是时区，如果只在电脑上编辑文件，不需要填写， Hexo 会根据本地电脑的时间生成
timezone: ''

# URL
## url 是设置站点的域名，可以使用 github 提供的 'https://username.github.io/project'
url: http://ooo.run
## permalink 是网站文章的链接格式
permalink: post/:title.html

permalink 指的是文章的 url 格式，我喜欢使用 post/:title.html 比较简洁，其中 :title 指的是文件名称。

hexo url preview

默认的是 :year/:month/:day/:title/ 会自动添加发布日期信息。

hexo url preview

编辑 yml 格式文件时，: 后面需要根一个空格，否则会报错，内容可以使用单引号包裹。

编辑后可以重新执行 hexo s 进行预览。

添加主题(Butterfly)

Hexo 支持很多主题，下面将使用并设置的是 Butterfly 主题。

先安装一下所需的依赖

1
npm install hexo-util moment-timezone hexo-renderer-pug hexo-renderer-stylus --save
1
pnpm install hexo-util moment-timezone hexo-renderer-pug hexo-renderer-stylus

打开终端，在博客目录下执行下面的命令下载主题

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

然后编辑博客目录下 _config.yml 文件，将底部的主题设置 theme: landscape 修改为 butterfly

1
theme: butterfly

运行 hexo s 预览主题效果。

为了避免主题未来更新覆盖了我们自定义的配置，可以复制一下主题的配置文件
Windows CMD

1
copy themes\butterfly\_config.yml _config.butterfly.yml

macOS / Linux 

1
cp themes/butterfly/_config.yml _config.butterfly.yml

然后我们就可以在博客目录下面的 _config.butterfly.yml 对主题进行自定义设置，可以修改一些功能以及设置导航菜单。

有关主题配置文件选项的中文标注可以查看 Butterfly 文档(三) 主题配置

添加文章

我们可以使用命令 hexo n postname 创建一个新的文章，这个命令等同于

1
hexo new post postname

这会在 source/_post 文件夹下面创建一个名称为 postname.md 的文件。

我们可以使用 VS Code 编辑这个文件，文章使用 Markdown 语法，打开这个文件后我们可以看到已自动填充了一些内容。 

1
2
3
4
5
---
title: postname
date: 2024-12-11 22:30:38
tags:
---

title 是现实的文章标题名称，date 是发布日期，tags 是文章的标签，这都是可以修改的，我们还可以添加更多的信息，比如分类和主图。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
# 必须部分
# 文章名称
title: 一个文章
# 发布日期
date: 2024-12-11 22:30:38

# 下面可选的
# 标签
tags:
 - 标签1
 - 标签2
# 分类
categories: 教程
# 关闭评论（默认是开启，可以不写）
comments: false

# 适用于 Butterfly 主题
# 缩略图
cover: 'https://arina.loli.net/2024/11/23/D3zqLFyGStUWQHZ.png'
---

# 在 --- 下面使用 Markdown 或是 HTML 语法写文章
# ...

插入图片

有时我们需要在图片中插入图片，我们只需要将图片放入 Hexo 目录中的 source 文件夹中，非常推荐单独建立一个文件夹比如 images 来存放图片。

假设我们有两张图片 1.png 与 2.png，此时文件目录是下面的样子 

1
2
3
4
source/
└── images/
    ├── 1.png
    └── 2.png

我们在文章中引用时，只需要使用下面的 Markdown 语法就可以了，路径以 / 开头，没有 source：

1
2
![](/images/1.png)
![2.png](/images/2.png)

虽然 VS Code 无法正常预览图片，但是通过 hexo s 在浏览器内预览就是正常的了。

添加一些页面（Pages）

除了文章之外，我们还需要添加一些页面（Pages）：

标签页

在 Hexo 的根目录运行

1
hexo new page tags

会生成 source/tags/index.md，编辑这个文件

1
2
3
4
5
6
7
8
---
title: 标签
date: 2024-12-13 07:55:00
type: 'tags'
orderby: random
order: 1
comments: false
---

就可以通过 http://localhost:4000/tags/ 或是 https://你的域名/tags 进行访问

分类页

在 Hexo 的根目录运行

1
2
3
4
5
6
7
8
9
10
11
hexo new page categories
```  
会生成 `source/categories/index.md`，编辑这个文件

```yml
---
title: 分类
date: 2024-12-13 07:00:00
type: 'categories'
comments: false
---

关于

在 Hexo 的根目录运行

1
2
3
4
5
6
7
8
9
10
11
hexo new page about
```  
会生成 `source/about/index.md`，编辑这个文件

```yml
---
title: 分类
date: 2024-12-13 07:00:00
---

# 以 Markdown 或是 HTML 格式编写内容

about 不是 Hexo 内置页面类型，不需要添加 types: 但是需要我们自己以 Markdown 或是 HTML 格式编写一些自我介绍。

将页面添加至导航

编辑主题的配置文件 _config.butterfly.yml，修改 menu 部分

1
2
3
4
5
6
menu:
  主页: / || fas fa-home
  分类: /categories/ || fas fa-archive
  标签: /tags/ || fas fa-tag
  关于: /about/ || fas fa-user
  友情链接: /link/ || fas fa-link

修改主题配置文件， hexo s 命令无法及时刷新预览，需要 Ctrl + C 终止后重新运行

保存后运行 hexo s 即可在右上角看到菜单。

部署到 GitHub

我们已经完成了主设置，并创建了新的文章，现在我们将把博客托管到 GitHub Pages 上，从而从网络上访问。

访问 https://github.com/new 创建一个新的仓库，Repository name 必须是 <username>.github.io，否则不会生效。

然后打开终端，安装 hexo-deployer-git 

1
npm install hexo-deployer-git --save
1
pnpm install hexo-deployer-git

然后编辑博客目录下的 _config.yml 文件，设置底部的 deploy 部分。

1
2
3
4
5
deploy:
  type: git
  # 仓库地址
  repo: https://github.com/<username>/<username>.github.io
  branch: gh-pages

首先打开终端，设置一下 Git 身份

1
2
3
4
5
6
# 设置 Git 身份
git config --global user.email "[email protected]"
git config --global user.name "Your Name"

# 让 Git 保存我们的登陆信息
git config --global credential.helper store

然后运行

1
2
hexo g
hexo d

我们需要对 Git 程序进行授权，弹窗点击 Sign in with your browser

image

下一步点击 Authorize git-ecosystem
image

再下一步后输入密码，即可完成部署。

即可将网站推送到 GitHub 上。

成功的话会输出类似下面内容

1
2
3
4
5
6
7
Writing objects: 100% (16/16), 1.27 KiB | 1.27 MiB/s, done.
Total 16 (delta 6), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (6/6), completed with 6 local objects.
To https://github.com/<yourname>/<xxxxxxxxx>.git
   812f2f9..5ff5eac  HEAD -> gh-pages
branch 'master' set up to track 'https://github.com/<yourname>/<xxxxxxxxx>.git/gh-pages'.
INFO  Deploy done: git

进阶教程：查看 如何使用 SSH key 连接 GitHub

设置 GitHub Pages

在 GitHub 仓库的网页上，点击顶部 Settings，左侧找到 Pages ，编辑 Branch 部分，设置为 gh-pages + /(root) 点击 Save 保存。

gh-page-settings

然后就可以访问 https://<username>.github.io 查看网站，如果显示 404 可以稍微等几分钟。

绑定域名

购买域名

如果你拥有一个属于自己的域名，那么除了使用 GitHub 提供的免费二级域名之外，我们还可以设置使用自己的域名访问博客。

如果你还没有域名，推荐前往下面的两个网站购买一个

  • Cloudflare 承诺以成本价销售域名，但是一般没有首年优惠
  • Porkbun 查询结果点击 Show All Extensions > Sort by price ，往往能看到不错的首年优惠
    通常推荐选择常用的后缀比如 .com 、.me 进行注册。

绑定至 GitHub

首先第一步前往域名服务商或是 Cloudflare ，在 DNS 设置中添加一条 CNAME 域名记录

  • 类型为 CNAME
  • 名称主域名填写 @ ( 代表 https://ooo.run )，也可以是 www 或一个其他的子域名
  • 内容是 username.github.io
cloudflare cname

第二步访问 GitHub 网站，在仓库的 Settings > Pages > Custon domain 中，填写我们的域名。

github-pages-custom-domain

第三步在 source 文件下创建一个 CNAME 文件，文件名是 大写字母，没有后缀，内容是我们需要使用的域名，比如 example.com。

最后运行命令将更新推送至 GitHub 就可以了。 

1
2
hexo g 
hexo d

然后就可以通过自己的域名访问博客了。

添加评论系统

Hexo 是不带评论系统的，需要我们自己添加，可以使用

  • 基于 GitHub 的 Giscus
  • 可以自己部署的 Twikoo 或 Arttalk
  • 第三方评论系统 Disqus (包含广告)

具体可以查看 为 Hexo 博客添加评论系统，Giscus or Twikoo or Arttalk or Disqus

常用的 Hexo 命令介绍

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 本地预览
hexo s
# 等同于
hexo server

# 生成站点
hexo g
# 等同于
hexo generate

# 部署
hexo d
# 等同于
hexo deploy 

# 清除缓存，有时遇到一些错误，可以先执行一下 hexo clean
hexo cl
# 等同于
hexo clean

进阶：使用 GitHub 备份

我们的博客数据源文件都保存在本地电脑上，如果更换电脑就需要手动进行备份。

在源文件中我们需要关注的是：

  • source 文件夹: 保存着博客文章的源文件，如果丢失就只能重新开始了
  • _config.yml: 保存着站点设置信息
  • _config.butterfly.yml: 保存着主题设置信息

最简单的方法是直接复制整个 Hexo 文件目录，手动拷贝到其他设备上，在新的设备上安装 Node.js 与 git 应用程序，适合只在特定设备写作需要更换设备时操作，毕竟手动复制在不同的设备上无法保持互相同步。

这里推荐使用 GitHub 备份我们整个 Hexo 文件夹。

下面介绍的是备份至博客同一个目录下，由于仓库是公开的，请不要再配置文件内记录密码或是其他敏感个人信息。

需要打开文件管理器删除主题目录 themes/butterfly 下的 .git 文件夹

image

macOS 可以按 Command + Shift+ . 显示隐藏文件夹

在 Hexo 根目录下执行下面的命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 初始化
git init

# 切换分支名称为 main
git branch -M main

# 追踪当前文件
git add .
git commit -m "first commit" --all

# 添加远程仓库，使用自己的仓库链接，替换 <username> 
git remote add origin https://github.com/<username>/<username>.github.io.git

# 推送到服务器
git push -u origin main

提交更新

在本地更新了之后，在 Hexo 目录下使用 git push 命令同步到 GitHub。

1
2
3
4
5
6
7
8
9
# 如果有写新文章
git add .

# 保存更新到本地 Git 
# -m "update" 用于备注更新内容， update 可以自定义修改
git commit -m "update" --all

# 同步到 GitHub
git push

此时访问 GitHub 仓库，点击顶部分支，其中 main 是存放我们备份的分支

image

获取备份

当 GitHub 文件比本地的新时（例如在别的设备更新过），在 Hexo 目录下使用 git pull 同步到本地

1
git pull

当我们更换一个全新的设备时，需要先安装 Node.js 与 git ，再从 GitHub 服务器获取备份 

1
2
3
4
5
6
7
8
9
10
11
# 将备份分支的数据下载到本地电脑
git clone -b main https://github.com/<username>/<username>.github.io.git 

# 进入 Hexo 目录
cd <username>.github.io.git

# 安装依赖
npm install

# 预览
hexo s

使用 Github Desktop

每次都敲命令太麻烦？ 安装 Github Desktop ！

我们就可以使用图形化界面简单的进行操作，首先是顶部右侧的按钮

  • 默认 Fetch origin 是检查更新
  • 当服务器比本地更新时，显示为 Pull origin 表示可以从 GiHub 获取更新
  • 当本地比服务器更新时，显示为 Push origin 表示可以推送更新到 GitHub
    本地更新后，可以在左下角 Summary 中填写注释，点击 Commit to main，就可以推送更新了

其他操作

给站点添加搜索功能

在 Hexo 根目录运行

1
npm install hexo-generator-searchdb --save
1
pnpm install hexo-generator-searchdb

修改站点配置文件 _config.yml，在最后新增

1
2
3
4
5
search:
  path: search.xml
  field: post
  content: true
  format: html

修改主题配置文件 _config.butterfly.yml

1
2
3
# 开启搜索
search:
  use: local_search

然后就可以执行搜索了

1
2
3
4
5
6
# 生成站点文件
hexo clean 
hexo g 

# 开启预览
hexo s

添加站点地图

在 Hexo 根目录下执行

1
npm install hexo-generator-sitemap --save
1
pnpm install hexo-generator-sitemap

以后生成站点信息时会自动生成 sitemap.xml 文件，本地 hexo s 预览可以通过 http://localhost:4000/sitemap.xml 访问

添加 RSS 支持

在 Hexo 根目录下执行

1
npm install hexo-generator-feed --save
1
pnpm install hexo-generator-feed

然后编辑 Hexo 根目录下的 _config.yml 文件，在最后添加

1
2
3
4
5
6
# RSS
feed:
  type: atom
  path: atom.xml
  # 限制输出文章数量
  limit: 20

以后生成站点信息时会自动生成 atom.xml 文件，本地 hexo s 预览可以通过 http://localhost:4000/atom.xml 访问

本地预览 atom.xml 显示乱码？ 不必担心，这是本地服务器的问题，atom.xml 文件其实是正常，推送到服务器后查看就可以了

设置友情链接

除了 Hexo 内置的几个页面 Type 之外，Butterly 主题还支持设置友情链接页面：
在 Hexo 的根目录运行

1
hexo new page link

会生成 source/link/index.md，编辑这个文件

1
2
3
4
5
---
title: 友情链接
date: 2024-12-13 07:00:05
type: 'link'
---

我们还需要在 source 文件夹下创建一个 _data 文件夹，再创建一个 link.yml 文件，按照下面的格式填写链接 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- class_name: 友情链接
  class_desc: 那些人，那些事
  link_list:
    - name: Hexo
      link: https://hexo.io/zh-tw/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: 快速、简单且强大的网志框架

- class_name: 网站
  class_desc: 值得推荐的网站
  link_list:
    - name: Youtube
      link: https://www.youtube.com/
      avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
      descr: 视频网站
    - name: Weibo
      link: https://www.weibo.com/
      avatar: https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png
      descr: 中国最大社交分享平台
    - name: Twitter
      link: https://twitter.com/
      avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
      descr: 社交分享平台