Hexo + GitHub Pages 搭建个人博客教程

, , ,

Hexo + GitHub Pages 搭建个人博客教程

作者： CaoZH
日期： 2024-10-15
本文为原创教程

2024 年已经有各种成熟的博客平台，但自建博客仍然是技术人绕不开的一个”成人礼”。Hexo 是 Node.js 生态中最流行的静态博客框架，配合 GitHub Pages 可以零成本搭建个人博客。

本文记录完整的搭建过程，从安装到自定义域名。

一、为什么选择 Hexo？

对比项 Hexo WordPress 博客园/CSDN
费用 免费 服务器费用 免费
自由度 完全控制 高 低
速度 静态页面，极快 动态，需数据库 一般
写作体验 Markdown 富文本 富文本
技术门槛 需要一点 CLI 低 无

二、环境准备

1
2
3
4
5
6
7
8
9
# 需要 Node.js（推荐 LTS 版本）
node -v          # v18.x+
npm -v           # v9.x+

# 安装 Hexo CLI
npm install -g hexo-cli

# 验证安装
hexo --version

三、初始化博客

1
2
3
4
5
6
7
8
9
10
# 创建博客项目
hexo init my-blog
cd my-blog

# 安装依赖
npm install

# 本地预览
hexo server
# 访问 http://localhost:4000

项目结构

1
2
3
4
5
6
7
8
my-blog/
├── _config.yml          # 站点配置文件（最重要的文件）
├── package.json
├── scaffolds/           # 模板
├── source/              # 源文件
│   └── _posts/          # 博客文章（Markdown 文件）
├── themes/              # 主题
└── public/              # 生成的静态文件（不要手动修改）

四、配置博客

编辑 _config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 站点信息
title: CaoZH 的笔记
subtitle: "个人技术笔记与经验分享"
description: "分享开发实战经验和学习笔记"
author: CaoZH
language: zh-CN
timezone: "Asia/Shanghai"

# URL
url: https://yourname.github.io
permalink: article/:title/    # 文章链接格式

# 主题
theme: landscape              # 默认主题

# 部署配置
deploy:
  type: git
  repo: https://github.com/yourname/yourname.github.io.git
  branch: gh-pages

五、安装主题

1
2
3
4
5
# 下载主题（以流行的 NexT 主题为例）
git clone https://github.com/theme-next/hexo-theme-next themes/next

# 修改 _config.yml
theme: next

每个主题都有自己的配置文件 themes/<主题名>/_config.yml，可以自定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 主题个性化配置
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th

# 社交链接
social:
  GitHub: https://github.com/yourname || fab fa-github

# 评论系统
valine:
  enable: true
  appid: your-app-id
  appkey: your-app-key

六、写文章

1
2
3
4
# 创建新文章
hexo new "我的第一篇文章"

# 文件生成在 source/_posts/2024-10-15-我的第一篇文章.md

文章格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
title: 我的第一篇文章
date: 2024-10-15 10:00:00
tags: [技术, 教程]
categories: 技术分享
---

# 文章标题

这里是正文，使用 Markdown 语法。

## 代码块

```python
print("Hello, Hexo!")

图片

图片描述

1
2
3
4
5
6
7
8
9
10
11

## 七、部署到 GitHub Pages

### 1. 创建 GitHub Pages 仓库

在 GitHub 创建仓库：`yourname.github.io`（必须是这个命名）

### 2. 安装部署插件

```bash
npm install hexo-deployer-git --save

3. 配置部署

编辑 _config.yml：

1
2
3
4
deploy:
  type: git
  repo: git@github.com:yourname/yourname.github.io.git
  branch: gh-pages

4. 一键部署

1
2
3
4
5
6
7
8
9
hexo clean     # 清除缓存
hexo generate  # 生成静态文件
hexo deploy    # 部署到 GitHub

# 以上三条命令等价于
hexo clean && hexo generate && hexo deploy

# 或简写
hexo d -g

5. 配置 GitHub Pages

  1. 进入仓库 Settings → Pages
  2. Source 选择 Deploy from a branch
  3. Branch 选择 gh-pages，目录 /root
  4. 等待几分钟，访问 https://yourname.github.io

八、自定义域名

方案一：GitHub 提供的域名

直接访问 https://yourname.github.io，零成本。

方案二：绑定自己的域名

  1. 购买域名（推荐 Namesilo / GoDaddy / 阿里云）
  2. 添加 CNAME 记录指向 yourname.github.io
1
2
3
4
# DNS 记录
类型: CNAME
名称: www / @
值  : yourname.github.io
  1. 在博客 source/ 目录下创建 CNAME 文件：
1
yourdomain.com
  1. 重新部署：
1
hexo clean && hexo d -g

九、常用命令速查

1
2
3
4
5
6
7
8
9
10
11
hexo new "文章标题"            # 新建文章
hexo new page "about"         # 新建页面
hexo generate                 # 生成静态文件
hexo server                   # 本地预览（http://localhost:4000）
hexo deploy                   # 部署
hexo clean                    # 清除缓存
hexo help                     # 帮助

# 组合命令
hexo d -g                     # 生成并部署
hexo s --debug                # 调试模式启动

十、进阶技巧

文章标签和分类

1
2
3
4
5
6
7
8
9
---
title: 文章标题
date: 2024-10-15
tags:
  - Vue
  - 前端
categories:
  - 前端开发
---

添加搜索功能

安装搜索插件：

1
npm install hexo-generator-searchdb --save

配置 _config.yml：

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

RSS 订阅

1
npm install hexo-generator-feed --save
1
2
3
4
feed:
  type: atom
  path: atom.xml
  limit: 20

十一、总结

通过本教程，你从零搭建了一个功能完整的个人博客：

步骤 内容
✅ Hexo 安装 脚手架初始化
✅ 主题配置 选择并自定义主题
✅ 文章写作 Markdown + Front-matter
✅ GitHub Pages 部署 一键发布
✅ 自定义域名 绑定自己的域名
✅ 进阶功能 搜索、RSS、标签分类

首发于 CaoZH 的笔记

CaoZHProgrammer

学习使我快乐。