Hexo 小白入门指南#

作为一个刚入门的小白，我在搭建 Hexo 博客的过程中踩了不少坑。这篇文章总结了我的学习经验，希望能帮助到同样是新手的你！

一、Hexo 是什么？#

Hexo 是一个快速、简洁且高效的静态博客框架。它使用 Markdown 解析文章，能在几秒内生成静态网页。

核心特点：

超快速度：Node.js 驱动，生成速度极快
支持 Markdown：专注写作，格式简洁
一键部署：轻松部署到 GitHub Pages
丰富的主题和插件生态

二、核心概念#

2.1 目录结构#

1
你的博客项目/
2
├── _config.yml          # 站点配置文件
3
├── _config.fluid.yml    # 主题覆盖配置（推荐）
4
├── package.json         # Node.js 依赖
5
├── source/              # 源文件目录
6
│   ├── _posts/          # 文章存放处
7
│   ├── _drafts/         # 草稿（不会发布）
8
│   ├── about/           # 关于页面（需手动创建）
9
│   └── images/          # 图片资源
10
├── themes/              # 主题目录
11
├── public/              # 生成的静态文件
12
└── node_modules/        # 依赖包

2.2 两个配置文件的区别#

文件	位置	作用
`_config.yml`	项目根目录	站点基本信息、URL、部署设置
`_config.fluid.yml`	项目根目录	主题个性化配置（覆盖主题默认设置）

为什么推荐用 _config.fluid.yml？

因为它不会被主题更新覆盖！直接修改 themes/fluid/_config.yml 的话，更新主题时你的配置就丢了。

2.3 页面类型#

类型	是否自动生成	说明
文章	✅ 自动	放在 `source/_posts/` 下的 md 文件
归档页	✅ 自动	内置生成器自动创建
标签页	✅ 自动	内置生成器自动创建
分类页	✅ 自动	内置生成器自动创建
关于页	❌ 手动	需要 `hexo new page about` 创建
友链页	❌ 手动	需要 `hexo new page links` 创建

三、常用命令#

3.1 基础命令#

1
# 创建新文章
2
hexo new "文章标题"
3
# 简写
4
hexo n "文章标题"
5

6
# 创建新页面（如关于页）
7
hexo new page about
8

9
# 生成静态文件
10
hexo generate
11
# 简写
12
hexo g
13

14
# 启动本地服务器预览
15
hexo server
16
# 简写
17
hexo s
18
# 指定端口
19
hexo s -p 4001
20

21
# 清除缓存和已生成的文件
22
hexo clean
23
# 简写
24
hexo cl
25

26
# 部署到远程服务器
27
hexo deploy
28
# 简写
29
hexo d

3.2 常用组合#

1
# 本地预览（清理 → 生成 → 启动服务）
2
hexo cl && hexo g && hexo s
3

4
# 部署上线（清理 → 生成 → 部署）
5
hexo cl && hexo g && hexo d
6

7
# 生成并部署
8
hexo g -d

四、写文章#

4.1 创建文章#

1
hexo new "我的第一篇文章"

这会在 source/_posts/ 下创建 我的第一篇文章.md 文件。

4.2 文章格式#

1
---
2
title: 文章标题
3
date: 2026-01-26 12:00:00
4
tags:
5
  - 标签1
6
  - 标签2
7
categories:
8
  - 分类名
9
---
10

11
这里是文章摘要，会显示在首页。
12

13
<!-- more -->
14

15
这里是正文内容，点击"阅读更多"才能看到。
16

17
## 二级标题
18

19
正文内容...
20

21
### 三级标题
22

23
更多内容...

4.3 Front-matter 说明#

文章开头 --- 之间的部分叫 Front-matter，常用字段：

字段	说明	示例
`title`	文章标题	`title: Hello World`
`date`	创建日期	`date: 2026-01-26 12:00:00`
`tags`	标签（可多个）	`tags: [Hexo, 教程]`
`categories`	分类	`categories: 技术`
`cover`	封面图	`cover: /images/cover.jpg`
`excerpt`	摘要	`excerpt: 这是摘要`

五、部署到 GitHub Pages#

5.1 前置准备#

注册 GitHub 账号
创建仓库，命名为 你的用户名.github.io
配置 SSH Key（用于免密推送）

5.2 安装部署插件#

1
npm install hexo-deployer-git --save

5.3 配置部署信息#

编辑 _config.yml：

1
deploy:
2
  type: git
3
  repo: git@github.com:你的用户名/你的用户名.github.io.git
4
  branch: master  # 或 main，取决于你的仓库设置

5.4 部署#

1
hexo cl && hexo g && hexo d

等待 1-3 分钟后访问 https://你的用户名.github.io/

六、常见问题#

Q1: Cannot GET /about/#

原因： 没有创建 about 页面

解决：

1
hexo new page about

Q2: 端口被占用#

错误信息： FATAL Port 4000 has been used

解决： 换个端口

1
hexo s -p 4001

Q3: 部署后网站没更新#

可能原因：

GitHub Pages 需要几分钟生效
浏览器缓存