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

本教程详细记录了使用 GitHub Pages 服务结合 Hexo 静态博客框架部署个人博客的完整流程。

环境准备

安装 Git

Windows 11 系统安装：

1	winget install --id Git.Git -e --source winget

验证安装：

1
2
3

git --version
# 输出示例：
# git version 2.50.0.windows.1

安装 Node.js
- 官方下载地址： https://nodejs.org/en/download/
- 验证安装：
  1
  2
  3
  node -v
  # 输出示例：
  # v22.16.0

安装 Hexo

Hexo 通过 npm 包管理器安装。建议先切换至国内镜像源加速下载（可选）：
1
npm config set registry https://registry.npmmirror.com
参考教程：npm 换源教程
安装 Hexo CLI：
1
npm install hexo-cli -g

验证安装：

hexo -v
# 输出示例 (版本号可能不同)：
# hexo-cli: 4.3.2
# os: win32 10.0.26100
# node: 22.16.0
# ...其他依赖信息...

安装 Hexo Git 部署插件
- 此插件用于将博客部署到 GitHub：
  1
  npm install hexo-deployer-git --save

配置 GitHub

配置 GitHub SSH 密钥

a. 生成 SSH Key：

1 2	ssh-keygen -t rsa -C "your_email@example.com" # 替换为你的 GitHub 注册邮箱 # 连续按三次回车键接受所有默认设置

b. 添加 SSH Key 到 GitHub：
1. 登录 GitHub，点击右上角头像 -> Settings。
2. 在左侧边栏选择 SSH and GPG keys。
3. 点击 New SSH key 按钮。
4. 在 Title 字段输入一个易于识别的名称（如 My PC Key）。
5. 打开本地生成的 id_rsa.pub 文件（通常在 ~/.ssh/ 目录下），复制其全部内容。
6. 将内容粘贴到 Key 文本框中。
7. 点击 Add SSH key。

c. 测试 SSH 连接：

ssh -T git@github.com
# 首次连接会询问是否继续，输入 `yes`
# 成功提示示例：
# Hi huanyuehjj! You've successfully authenticated, but GitHub does not provide shell access.

d. 配置 Git 全局用户信息：

1 2	git config --global user.name "huanyuehjj" # 替换为你的 GitHub 用户名 git config --global user.email "hjj_huanyue@outlook.com" # 替换为你的 GitHub 注册邮箱

创建与配置本地博客

初始化 Hexo 博客

创建一个空文件夹作为你的博客根目录，进入该目录。
初始化项目：
1
hexo init
安装项目依赖：
1
npm install

关键目录结构说明：

.
├── _config.yml       # 站点主配置文件
├── package.json      # 项目依赖信息
├── package-lock.json # 依赖锁定文件
├── scaffolds/        # 文章模板文件夹
├── source/           # 存放博客文章 (Markdown) 和页面
├── themes/           # 存放博客主题
└── node_modules/     # 项目依赖包 (由 npm install 生成)

生成静态文件并启动本地预览服务器：
1
2
hexo generate # 或简写 hexo g
hexo server # 或简写 hexo s
- 成功启动后，命令行会显示：
  1
  INFO Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.
- 打开浏览器访问 http://localhost:4000 即可查看本地博客。
注意： 此服务仅在本地运行，需部署到 GitHub Pages 才能对外访问。

更换主题 (以 Stellar / Next 为例)
- 方式一：手动下载 (如 Stellar)
  1. 访问主题的 GitHub 仓库 (如：https://github.com/xaoxuu/hexo-theme-stellar)。
  2. 下载 ZIP 压缩包。
  3. 解压到博客根目录下的 themes/ 文件夹中，确保主题文件夹名为 stellar。
- 方式二：Git 克隆 (如 Next)
  1
  2
  # 在博客根目录执行：
  git clone https://github.com/theme-next/hexo-theme-next.git themes/next
- 启用主题： 修改博客根目录下的 _config.yml 文件，找到 theme 字段：
  1
  2
  3
  4
  # Extensions
  ## Plugins: https://hexo.io/plugins/
  ## Themes: https://hexo.io/themes/
  theme: stellar # 或 next，与你在 themes/ 下的文件夹名一致
- 应用主题配置： 不同主题通常有独立的配置文件（如 themes/stellar/_config.yml），请查阅主题文档进行详细配置。
提示： Hexo 官网的主题页面提供了丰富的主题选择。

部署到 GitHub Pages

创建 GitHub Pages 仓库
- 在 GitHub 上创建一个新的仓库。
- 仓库名必须严格遵守格式： 你的GitHub用户名.github.io (例如：huanyuehjj.github.io)。这个仓库名将直接作为你博客的访问地址。

配置 Hexo 部署信息

编辑博客根目录下的 _config.yml 文件：

设置博客 URL (通常在文件开头附近)：

# Site
title: Your Blog Title
subtitle: ''
description: ''
keywords:
author: Your Name
language: zh-CN
timezone: ''
url: https://huanyuehjj.github.io  # 替换为你的 GitHub Pages 地址

配置部署选项 (在文件末尾附近)：

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repo: git@github.com:huanyuehjj/huanyuehjj.github.io.git # 替换为你的仓库 SSH 地址
  branch: main # 或 master，根据你的仓库默认分支名

部署博客
- 确保已安装 hexo-deployer-git 插件 (见步骤 4)。
- 执行部署命令：
  1
  2
  3
  hexo clean # 清除缓存和旧文件 (可选但推荐)
  hexo generate # 重新生成静态文件
  hexo deploy # 或简写 hexo d，部署到 GitHub
- 首次部署可能需要输入 GitHub 账户密码或授权。
- 部署完成后，稍等几分钟（GitHub Pages 需要构建），在浏览器访问 https://你的GitHub用户名.github.io (例如：https://huanyuehjj.github.io) 即可看到你的在线博客。

恭喜！

至此，你的个人博客已成功部署到 GitHub Pages！接下来，你可以专注于编写博客内容，并深入探索 Hexo 的配置选项（如站点信息、主题样式、插件等）来个性化你的博客。