从零开始搭建 Hexo 个人博客 - 详细入门教程

想要搭建一个属于自己的静态博客？Hexo 是一个非常好的选择！本文将带你从零开始，一步步搭建一个美观的 Hexo 博客。

前置要求

在开始之前，请确保你的电脑已经安装了以下软件：

安装 Node.js

Hexo 基于 Node.js，所以需要先安装 Node.js。

下载地址：https://nodejs.org/

推荐下载 LTS 长期支持版，安装时一路下一步即可。

安装完成后，打开命令提示符（CMD）或 PowerShell 验证：

1
2
node -v
npm -v

如果显示版本号，说明安装成功。

安装 Git（可选但推荐）

Git 用于代码版本管理和部署到 GitHub Pages。

下载地址：https://git-scm.com/downloads

安装完成后验证：

1
git --version

安装 Hexo

安装好 Node.js 后，我们就可以用 npm 安装 Hexo 了。

打开命令提示符，执行：

1
npm install -g hexo-cli

安装完成后验证：

1
hexo -v

如果显示版本信息，说明 Hexo 安装成功！

初始化项目

创建博客文件夹

选择一个你喜欢的位置，创建博客文件夹，比如 blog：

1
2
3
4
5
# 创建文件夹
mkdir blog

# 进入文件夹
cd blog

初始化 Hexo

1
hexo init

这个过程需要下载依赖，耐心等待一下。

安装依赖

1
npm install

初始化完成后，项目结构应该是这样：

1
2
3
4
5
6
7
8
9
blog/
├── node_modules/    # 依赖包
├── scaffolds/       # 文章模板
├── source/          # 文章和页面存放位置
├── themes/          # 主题存放位置
├── .gitignore       # Git 忽略文件
├── _config.yml      # Hexo 主配置文件
├── package.json     # 依赖信息
└── README.md        # 说明文件

安装 Butterfly 主题

这里我们使用非常流行的 Butterfly 主题，它美观、功能丰富，持续维护。

下载主题

在博客根目录执行：

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

应用主题

打开根目录下的 _config.yml，找到 theme 这一项，修改为：

1
theme: butterfly

安装依赖

Butterfly 需要一些额外依赖：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

配置主题

创建主题配置文件

在根目录创建 _config.butterfly.yml 文件，这是 Butterfly 主题的配置文件。

可以直接从主题目录复制：

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

这样以后主题更新时，不会覆盖你的配置。

修改站点信息

编辑根目录 _config.yml，修改基本信息：

1
2
3
4
5
6
7
# Site
title: 你的博客标题       # 站点标题
subtitle: 你的副标题      # 副标题
description: '博客描述'    # 描述
author: 你的名字          # 作者
language: zh-CN           # 语言（简体中文）
timezone: Asia/Shanghai   # 时区

配置菜单导航

编辑 _config.butterfly.yml 的 menu 部分：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
menu:
  主页: / || fas fa-home
  博文 || fa fa-graduation-cap:
    分类: /categories/ || fa fa-archive
    标签: /tags/ || fa fa-tags
    归档: /archives/ || fa fa-folder-open
  生活 || fas fa-list:
    分享: /shuoshuo/ || fa fa-comments-o
    相册: /photos/ || fa fa-camera-retro
    音乐: /music/ || fa fa-music
    影视: /movies/ || fas fa-video
  友链: /links/ || fa fa-link
  留言板: /comment/ || fa fa-paper-plane
  关于笔者: /about/ || fas fa-heart

创建对应页面

根据菜单配置，我们需要创建对应的页面：

1
2
3
4
5
6
7
8
# 创建各个页面目录
hexo new page shuoshuo
hexo new page photos
hexo new page music
hexo new page movies
hexo new page links
hexo new page comment
hexo new page about

创建完成后，在 source/ 目录下会出现对应的文件夹和 index.md。

编辑每个 index.md，在 front-matter 添加 type 声明：

1
2
3
4
5
6
---
title: 分享
date: 2026-06-17 15:00:00
type: shuoshuo
comments: true
---

按照这个方式给所有页面添加 type。

本地预览

配置完成后，我们可以在本地预览效果。

生成静态文件

1
2
3
hexo generate
# 简写
hexo g

启动本地服务器

1
2
3
hexo server
# 简写
hexo s

默认会启动在 http://localhost:4000，打开浏览器访问就能看到你的博客了！

hexo server 会自动监听文件变化，修改后刷新页面就能看到最新效果。

写文章

创建文章

使用 Hexo 命令创建新文章：

1
hexo new post "文章标题"

文章会创建在 source/_posts/文章标题.md。

文章格式

Hexo 使用 Markdown 语法写文章，开头需要有 front-matter：

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 文章标题       # 文章标题
date: 2026-06-17 15:00:00  # 创建日期
tags:                   # 标签
  - Hexo
  - 教程
categories:            # 分类
  - 技术
description: '文章描述' # 描述（可选）
---

这里是文章正文...

常用 Markdown 语法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 一级标题
## 二级标题
### 三级标题

**加粗文字**
*斜体文字*

> 引用

- 列表项1
- 列表项2
- 列表项3

[链接文字](https://example.com)
![图片说明](图片链接)

| 表头1 | 表头2 |
|-------|-------|
| 内容1 | 内容2 |

部署到 GitHub Pages

创建 GitHub 仓库

登录 GitHub，创建一个名为 你的用户名.github.io 的仓库。

安装部署插件

在项目根目录执行：

1
npm install hexo-deployer-git --save

配置部署信息

编辑根目录 _config.yml，在最后添加：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: master

部署

1
2
3
hexo clean && hexo generate && hexo deploy
# 简写
hexo clean && hexo g && hexo d

输入你的 GitHub 账号密码，部署完成后，等待几分钟，访问 https://你的用户名.github.io 就能看到你的博客了！

常用命令总结

命令 说明 简写
hexo init 初始化博客 -
hexo new post "标题" 创建新文章 hexo n "标题"
hexo generate 生成静态文件 hexo g
hexo server 启动本地服务器 hexo s
hexo clean 清除缓存 hexo clean
hexo deploy 部署 hexo d
hexo clean && hexo g && hexo d 清除+生成+部署 常用组合

常见问题

Q1: 启动服务器后端口被占用怎么办？

1
hexo server -p 8080

指定其他端口即可。

Q2: 修改配置后不生效？

先清除缓存再重新生成：

1
hexo clean && hexo g

Q3: 图片怎么放？

推荐两种方式：

  1. 和文章放在一起：在 source/_posts/ 创建和文章同名的文件夹，然后用相对路径引用
  2. 统一存放：放在 source/img/ 目录下，使用 /img/xxx.jpg 引用

Q4: 怎么绑定自己的域名？

在 GitHub 仓库设置中找到 Pages，在 Custom domain 填写你的域名，然后添加 DNS 解析即可。

进阶优化

  • 评论系统：集成 Valine、Disqus、Gitalk 等评论系统
  • 搜索功能：启用本地搜索
  • 字数统计：显示文章字数和阅读时长
  • 图片懒加载：优化加载速度
  • CDN 加速：使用 CDN 加速静态资源
  • 自定义样式：根据喜好修改主题样式

参考链接

结束语

恭喜你！现在你已经拥有了一个属于自己的静态博客了！

如果这篇教程对你有帮助，欢迎在下方留言交流。有问题也可以留言，我会尽力解答。

写作日期：