Hexo博客搭建基础教程

大家好，今天我将为大家带来一篇详细的Hexo博客搭建教程。通过这篇教程，你将能够从零开始搭建一个个人博客，并且完全免费。Hexo是一个快速、简洁且高效的博客框架，使用Markdown语法来编写文章，可以轻松地将静态网页部署到GitHub Pages或Cloudflare Pages等平台。

1. 事前准备

在开始搭建博客前，我们需要准备以下几项：

1. 域名（非必须，可以使用免费域名，或者GitHub.io或Pages.dev分配的域名）
2. GitHub账号（必须，需要注册一个GitHub帐号用于托管博客）
3. Cloudflare账号（非必须，可以用于CDN加速，也可以直接使用GitHub.io分配的域名）

2. 软件支持

进行Hexo博客搭建，我们需要以下软件：

1. Node.js（必须）
2. Git（必须）
3. VSCode（非必须，轻量型代码编辑器，有助于养成良好编程习惯）

2.1. 安装Node.js

1. 前往Node.js官网下载与系统相匹配的安装程序
2. 安装时使用默认目录C:/Program Files/nodejs/
3. 安装完成后，验证安装：按Win+R打开CMD窗口，执行以下命令：

1
2

# 在CMD或PowerShell窗口中执行
node -v

4. 修改npm源以加快下载速度：

1
2

# 在CMD或PowerShell窗口中执行
npm config set registry https://mirrors.huaweicloud.com/repository/npm/

2.2. 安装Git

1. 前往Git官网下载适合当前系统的版本
2. 按默认设置安装，推荐使用默认目录C:/Program Files/Git
3. 安装完成后，可以在开始菜单找到以下三个程序：
   • Git CMD：Windows命令行风格
   • Git Bash：Linux系统命令风格（推荐使用）
   • Git GUI：图形界面（不建议新手使用）

3. 配置Git密钥并连接至Github

3.1. 配置用户名和邮箱

打开Git Bash（从开始菜单或右键菜单中选择），输入以下命令配置用户名和邮箱：

1
2
3

# 在Git Bash中执行
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

3.2. 配置公钥连接Github

1. 在Git Bash中生成SSH密钥：

1
2

# 在Git Bash中执行
ssh-keygen -t rsa -C "你的邮箱"

按三次回车即可生成密钥（默认保存位置、无密码保护）

2. 在Git Bash中查看公钥：

1
2

# 在Git Bash中执行
cat ~/.ssh/id_rsa.pub

或在Windows资源管理器中打开文件C:\Users\你的用户名\.ssh\id_rsa.pub

3. 复制公钥内容，登录GitHub网站，进入Settings -> SSH and GPG keys -> New SSH key，将公钥粘贴进去，点击Add SSH key

4. 在Git Bash中验证连接：

1
2

# 在Git Bash中执行
ssh -T git@github.com

如果是首次连接，会出现以下提示：

1
2
3

The authenticity of host 'github.com (20.205.243.166)' can't be established.
ECDSA key fingerprint is SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入yes并按回车继续。随后如果看到类似以下信息：

1

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

则表示SSH连接验证成功，至此完成了所有环境准备工作。

3.3. 创建GitHub.io仓库

1. 在浏览器中登录GitHub，点击右上角”+”，选择”New repository”
2. 仓库名称必须为用户名.github.io（例如：username.github.io）
3. 选择Public可见性，不需要添加README文件
4. 点击”Create repository”完成创建

4. 初始化Hexo博客

1. 全局安装Hexo命令行工具：

1
2

# 在CMD或PowerShell窗口中执行
npm install -g hexo-cli

2. 创建博客目录并初始化：

1
2
3
4
5
6
7
8
9

# 在你想要创建博客的位置打开终端，执行：
mkdir blog
cd blog

# 初始化Hexo
hexo init

# 安装依赖
npm install

3. 安装Git部署插件：

1
2

# 在博客根目录下的终端中执行
npm install hexo-deployer-git --save

4. 修改Hexo配置文件：
   • 使用VSCode或任何文本编辑器打开博客根目录下的_config.yml文件
   • 找到deploy部分并修改为：

1
2
3
4

deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io.git
  branch: master  # GitHub可能默认使用main或master作为主分支

注意：根据GitHub的最新政策，新创建的仓库默认分支名可能是main而不是master。请确认你的GitHub仓库默认分支名称，并相应地设置branch值。

5. 本地预览博客：

1
2
3
4
5
6
7
8
9
10
11

# 在博客根目录下的终端中执行

# 生成静态文件
hexo generate
# 或简写
hexo g

# 启动本地服务器
hexo server
# 或简写
hexo s

然后在浏览器访问http://localhost:4000查看效果

5. 将静态博客挂载到GitHub Pages

1. 生成并部署博客：

1
2
3
4
5
6
7
8
9
10
11
12

# 在博客根目录下的终端中执行

# 清理缓存
hexo clean

# 生成静态文件
hexo generate

# 部署到GitHub
hexo deploy
# 或简写
hexo d

2. 部署完成后，等待几分钟，然后访问https://你的用户名.github.io查看你的博客

6. 将静态博客挂载到Cloudflare Pages

除了GitHub Pages，你还可以将博客部署到Cloudflare Pages，这样可以获得更好的访问速度和更多的功能。

1. 在浏览器中注册并登录Cloudflare账号
2. 在Cloudflare控制面板中，点击”Pages”
3. 点击”Create a project”，选择”Connect to Git”
4. 授权并选择你的GitHub仓库
5. 配置构建设置：
   • 项目名称：自定义（如my-blog）
   • 生产分支：master（或你的默认分支名）
   • 构建命令：npm run build或hexo generate
   • 构建输出目录：public
6. 点击”Save and Deploy”开始部署
7. 部署完成后，Cloudflare会提供一个*.pages.dev域名（如my-blog.pages.dev）访问你的博客

7. 如何使用

7.1. 新建一篇博文

在博客根目录下执行以下命令创建一篇新文章：

1
2

# 在博客根目录下的终端中执行
hexo new "文章标题"

这会在source/_posts目录下创建一个新的Markdown文件，可以使用VSCode或其他编辑器打开编辑

7.2. 本地预览

编辑完文章后，执行以下命令在本地预览效果：

1
2
3
4
5
6
7
8
9
10

# 在博客根目录下的终端中执行

# 清理缓存
hexo clean

# 生成静态文件
hexo g

# 启动本地服务器
hexo s

然后在浏览器访问http://localhost:4000查看效果。

7.3. 发布文章

确认无误后，执行以下命令将本地文章推送至GitHub仓库：

1
2
3
4
5
6
7
8
9

# 在博客根目录下的终端中执行

# 清理缓存
hexo clean

# 生成并部署
hexo g -d
# 或
hexo generate --deploy

8. VSCode终端首次执行报错解决方案

如果在VSCode终端中执行Hexo命令时出现错误，可能是因为PowerShell的执行策略限制。解决方法：

1. 以管理员身份运行PowerShell（在开始菜单中右键点击PowerShell，选择”以管理员身份运行”）
2. 执行以下命令：

1
2

# 在管理员权限的PowerShell中执行
Set-ExecutionPolicy RemoteSigned

3. 输入”Y”确认更改
4. 重新打开VSCode尝试执行Hexo命令

9. 常用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

# 在博客根目录下的终端中执行

# 创建新文章
hexo new "文章标题"

# 生成静态文件
hexo generate
hexo g

# 启动本地服务器
hexo server
hexo s

# 部署网站
hexo deploy
hexo d

# 清理缓存
hexo clean

# 生成并部署
hexo g -d

# 创建新页面
hexo new page "页面名称"

# 查看Hexo版本
hexo version

10. 注意事项

1. 终端位置很重要：所有Hexo命令都必须在博客根目录下执行，否则会报错
2. 命令执行环境：
   • Node.js和npm相关命令可在CMD、PowerShell或Git Bash中执行
   • Git配置和SSH密钥生成推荐在Git Bash中执行
   • Hexo命令可在任何终端中执行，但必须确保在博客根目录下
3. 路径问题：Windows系统中，如果路径包含空格或特殊字符，可能需要使用引号括起来
4. 权限问题：如果遇到权限错误，可以尝试以管理员身份运行终端

11. 实用技巧

11.1. 自动生成目录页面

为了让博客更加完整，你可能需要创建分类页面、标签页面和关于页面：

1
2
3
4
5
6
7
8

# 创建分类页面
hexo new page categories

# 创建标签页面
hexo new page tags

# 创建关于页面
hexo new page about

然后分别编辑这些页面的Markdown文件，添加以下内容：

对于source/categories/index.md：

1
2
3
4
5
6
7

---
title: 分类
date: 2024-07-05 03:36:48
aside: false
top_img: false
type: "categories"
---

对于source/tags/index.md：

1
2
3
4
5
6
7

---
title: 标签
date: 2024-07-05 03:36:02
type: "tags"
comments: false
top_img: false
---

11.2. 添加文章永久链接

为了让你的文章链接更加稳定，可以安装永久链接插件：

1

npm install hexo-abbrlink --save

然后在_config.yml中修改永久链接设置：

1
2
3
4

permalink: posts/:abbrlink/
abbrlink:
  alg: crc32
  rep: hex

11.3. 添加本地搜索功能

安装搜索插件：

1

npm install hexo-generator-searchdb --save

然后在_config.yml中添加配置：

1
2
3
4
5

search:
  path: search.xml
  field: post
  content: true
  format: html

12. 总结

通过本教程，我们完成了基于Hexo框架的个人博客搭建。从环境配置、初始化到部署，每一步都有详细的说明。我们还介绍了如何将博客部署到GitHub Pages和Cloudflare Pages，以及一些常见问题的解决方法和实用技巧。

这种方式搭建的博客完全免费，无需购买服务器，只需要一些基础的编程知识即可完成。在下一篇文章中，我们将介绍如何安装和配置美观的AnZhiYu主题，让你的博客更加个性化。

如果在搭建过程中遇到任何问题，欢迎在评论区留言讨论。祝你的博客之旅愉快！