使用 Hexo + GitHub Pages 搭建个人静态博客

前言

GitHub Pages 是 GitHub 提供的免费静态页面托管服务，配合 Hexo 这个快速、简洁的静态博客框架，可以零成本搭建一个属于自己的技术博客。全程不需要购买服务器，只需要熟悉基本的命令行操作。

一、环境准备

1.1 安装 Node.js（使用 nvm 管理版本）

推荐使用 nvm 安装 Node.js，便于后续版本管理（可参考《使用 nvm 安装 Node.js》）。

1
2
3
4
nvm install 22.15.0
nvm use 22.15.0
node -v   # 验证安装成功
npm -v

1.2 安装 Git

  • Windows 用户前往 git-scm.com 下载安装。
  • 安装后验证：
1
git --version

1.3 配置 Git 全局信息

1
2
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

二、注册并配置 GitHub

2.1 注册 GitHub 账号

前往 github.com 注册账号（已有则跳过）。

2.2 创建 GitHub Pages 仓库

关键步骤：仓库名必须遵循固定格式。

  1. 点击 New repository；
  2. 仓库名填写 你的用户名.github.io（例如 likerhood.github.io）；
  3. 权限设置为 Public；
  4. 不要勾选初始化 README；
  5. 点击 Create repository。

创建成功后，GitHub 会自动为该仓库启用 GitHub Pages，访问地址即为 https://你的用户名.github.io。

2.3 配置 SSH 密钥（推荐）

配置 SSH 可以让 Hexo 免密码推送。

1
2
3
4
5
# 生成 SSH 密钥对
ssh-keygen -t rsa -b 4096 -C "你的邮箱"

# 查看公钥内容（复制全部内容）
cat ~/.ssh/id_rsa.pub

将公钥粘贴到 GitHub → Settings → SSH and GPG keys → New SSH key。

验证：

1
2
ssh -T git@github.com
# 出现 "Hi xxx! You've successfully authenticated." 即为成功

三、安装并初始化 Hexo

3.1 全局安装 Hexo CLI

1
npm install -g hexo-cli

3.2 初始化博客目录

1
2
3
4
# 在你希望存放博客的位置执行
hexo init myblog
cd myblog
npm install

初始化后的目录结构如下：

1
2
3
4
5
6
7
8
myblog/
├── _config.yml          # 站点全局配置（核心）
├── package.json
├── scaffolds/           # 文章模板
├── source/
│   ├── _posts/          # 博客文章存放目录
│   └── about/
└── themes/              # 主题目录

3.3 本地预览

1
2
hexo server
# 访问 http://localhost:4000

四、站点全局配置

编辑根目录下的 _config.yml，常用配置如下：

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
# 站点基本信息
title: Liker's Blog
subtitle: '记录技术成长，分享生活点滴'
author: Like
language: zh-CN
timezone: 'Asia/Shanghai'

# 博客访问地址（必须与 GitHub Pages 仓库名一致）
url: https://你的用户名.github.io

# 代码高亮（必须显式启用，否则主题的 mac 风格代码框无法渲染）
syntax_highlighter: highlight.js
highlight:
  enable: true
  line_number: true
  auto_detect: false
  wrap: true
  hljs: false

# 主题
theme: hexo-theme-bcxm

# 部署配置
deploy:
  type: 'git'
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main

⚠️ 注意：highlight.enable: true 是让主题的代码工具栏（mac 风格三色点、复制按钮、语言标签）正常显示的关键配置，缺少此项会导致所有代码块工具栏不渲染。

五、安装与配置主题

以 hexo-theme-bcxm 主题为例。

5.1 下载主题

1
2
3
4
# 方式一：git clone（推荐）
git clone https://github.com/chenxz21/hexo-theme-bcxm themes/hexo-theme-bcxm

# 方式二：手动下载 zip 并解压到 themes 目录

5.2 修改站点配置使用主题

1
2
# _config.yml
theme: hexo-theme-bcxm

5.3 主题配置文件

主题配置文件位于 themes/hexo-theme-bcxm/_config.yml，核心配置项包括：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 代码块样式（mac / mac light / darker / pale night / ocean / light）
highlight_theme: mac
highlight_copy: true     # 显示复制按钮
highlight_lang: true     # 显示语言标签
highlight_shrink: false  # 是否默认折叠代码块
highlight_height_limit: 500  # 超出此高度则折叠（单位：px）

# 头像
avatar:
  img: /img/avatar.jpg

# 社交链接
social:
  Github: https://github.com/你的用户名 || fab fa-github
  Email: mailto:你的邮箱 || fas fa-envelope

六、写文章

6.1 新建文章

1
2
hexo new post "文章标题"
# 会在 source/_posts/ 下生成对应的 .md 文件

6.2 文章 Front Matter

文章头部的 YAML 声明块，用于设置元数据：

1
2
3
4
5
---
title: 使用nvm安装node.js
date: 2026-04-10 16:44:23
categories: 工具安装教程
---

6.3 文章正文

支持标准 Markdown 语法，代码块语法如下：

1
2
3
```bash
nvm install 22.15.0
```

七、部署到 GitHub Pages

7.1 安装部署插件

1
npm install hexo-deployer-git --save

7.2 本地生成静态文件并部署

1
2
3
4
# 三步走（每次修改后重复执行）
hexo clean       # 清除旧的生成文件（缓存）
hexo generate    # 重新生成静态文件到 public/
hexo deploy      # 推送 public/ 到 GitHub Pages 仓库

也可以合并执行：

1
hexo clean; hexo g -d

7.3 验证部署

等待 1~3 分钟后，访问 https://你的用户名.github.io，确认博客正常显示。

八、日常维护流程

1
2
3
4
5
6
7
8
9
写文章（.md）
     ↓
hexo clean
     ↓
hexo generate（本地预览确认：hexo server）
     ↓
hexo deploy（推送到 GitHub）
     ↓
等待片刻后访问博客

九、常见问题与注意事项

问题 原因 解决方案
代码块没有 mac 三色点工具栏 根配置 highlight.enable 未设置 true 在 _config.yml 中添加 highlight.enable: true
部署成功但页面没更新 浏览器缓存 / GitHub Pages 未刷新 强制刷新（Ctrl+Shift+R）或等待几分钟
hexo deploy 报错 未安装部署插件 npm install hexo-deployer-git --save
主题样式不生效 修改了主题 Stylus 文件但未重新生成 每次改样式后都要重新 hexo g
图片不显示 路径错误或未放到 source/img/ 目录 统一将图片放入 source/img/，引用 /img/filename.jpg
文章 [toc] 不渲染为目录 部分主题/插件不支持此语法 使用主题内置的目录侧边栏代替，或安装 hexo-toc 插件

十、参考资源

总结

本文完整记录了从零搭建一个 Hexo + GitHub Pages 个人博客的全过程，可以归纳为以下五个阶段：

  1. 环境搭建：安装 Node.js（推荐 nvm 管理版本）和 Git，配置好本地开发基础；
  2. GitHub 配置：创建命名为 用户名.github.io 的仓库，配置 SSH 密钥实现免密推送；
  3. Hexo 初始化：全局安装 Hexo CLI，初始化博客目录，本地 hexo server 预览确认环境正常；
  4. 主题与配置：在站点 _config.yml 中完成 URL、高亮、部署等核心配置，安装并调整主题样式；
  5. 写作与发布：用 Markdown 写文章，通过 hexo clean → hexo generate → hexo deploy 三步将内容推送上线。

整个方案的优势在于完全免费、无需服务器，同时 Hexo 生成的是纯静态 HTML，加载速度快、安全性高。后续维护也极为简单，只需专注于写 Markdown 文章，剩下的交给 Hexo 和 GitHub 自动完成。

💡 给自己的一条建议：搭建博客只是起点，坚持输出内容才是关键。哪怕每周一篇学习笔记，时间久了就是一份非常有价值的个人知识沉淀。