🚀 从零开始搭建 Hexo 博客并部署到 GitHub Pages（超详细图文教程）

本教程适合没有任何博客搭建经验的朋友，从环境配置到博客部署，手把手教你创建一个属于自己的静态博客，并成功发布到 GitHub Pages！

🧰 一、准备工作

1. 安装 Node.js（Hexo 运行环境）

• 打开官网：https://nodejs.org/
• 推荐下载 LTS（长期支持版）
• 一路默认安装即可（安装过程中勾选“添加到 PATH”）

安装验证：

打开命令提示符（Win+R 输入 cmd），输入以下命令：

1
2

node -v
npm -v

正常显示版本号则说明安装成功。

2. 安装 Git（Hexo 依赖 Git 来部署）

• 打开官网：https://git-scm.com/
• 默认设置安装（点击“下一步”到底）
• 安装完成后，右键可以看到“Git Bash Here”

安装验证：

在命令行中输入：

1
2
3
4
5

bash


复制编辑
git --version

正常显示版本号即可。

3. 安装 Hexo CLI（全局安装）

打开命令提示符或 PowerShell 输入：

1
2
3
4
5

bash


复制编辑
npm install -g hexo-cli

成功后输入：

1
2
3
4
5

bash


复制编辑
hexo -v

输出 Hexo 版本号，说明安装成功。

📁 二、创建博客项目

1. 打开命令行，进入你想存放博客的位置：

1
2
3
4
5

bash


复制编辑
cd D:\

2. 初始化 Hexo 博客：

1
2
3
4

bash复制编辑
hexo init my-blog
cd my-blog
npm install

Hexo 会自动生成以下目录结构：

1
2
3
4
5
6
7
8

bash复制编辑
my-blog/
├── _config.yml        # 博客主配置文件
├── package.json       # 依赖管理文件
├── public/            # 静态网页（部署使用）
├── scaffolds/         # 模板
├── source/            # 存放文章和页面资源
├── themes/            # 存放主题

🖥️ 三、本地预览你的博客

在项目目录下启动本地服务：

1
2
3
4
5

bash


复制编辑
hexo server

在浏览器访问：http://localhost:4000

如果看到 Hexo 欢迎页，就表示博客已经初始化成功了！

✍️ 四、撰写文章

新建文章命令：

1
2
3
4
5

bash


复制编辑
hexo new "我的第一篇文章"

它会在 source/_posts 文件夹生成一个 Markdown 文件：

1
2
3
4
5
6
7
8
9

markdown复制编辑---
title: 我的第一篇文章
date: 2025-07-22 15:00:00
tags:
- Hexo
- 教程
---

这里是正文内容，可以使用 Markdown 编写格式化文本。

撰写完成后运行：

1
2
3
4

bash复制编辑
hexo clean
hexo g
hexo s

再次访问 http://localhost:4000 就能看到你的文章了！

🎨 五、更换主题（以 Next 为例）

1. 克隆 Next 主题到 themes 文件夹

1
2
3

bash复制编辑
cd themes
git clone https://github.com/theme-next/hexo-theme-next next

2. 修改博客配置文件 _config.yml：

1
2
3
4
5

yaml


复制编辑
theme: next

3. 重新生成：

1
2
3
4

bash复制编辑
hexo clean
hexo g
hexo s

刷新页面即可看到新主题。

🌍 六、部署到 GitHub Pages

1. 创建 GitHub 仓库

1. 登录 GitHub：https://github.com
2. 点击右上角 ➕ → New repository
3. 仓库名称填写为：你的用户名.github.io（必须一致）
4. 不勾选 README、license，直接创建

2. 安装部署插件

在博客项目根目录执行：

1
2
3
4
5

bash


复制编辑
npm install hexo-deployer-git --save

3. 修改根目录的 _config.yml 配置部署信息：

1
2
3
4
5

yaml复制编辑
deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main  # 或 master，具体看你仓库的默认分支

4. 设置 Git 用户信息（首次部署需配置）

1
2
3

bash复制编辑
git config --global user.name "你的GitHub用户名"
git config --global user.email "你GitHub绑定的邮箱"

5. 构建并部署：

1
2
3
4

bash复制编辑
hexo clean
hexo generate
hexo deploy

终端提示 Deploy done 即代表部署成功。

6. 访问你的网站！

打开浏览器访问：

1
2
3
4
5

cpp


复制编辑
https://你的用户名.github.io

恭喜你！你的 Hexo 博客已经上线了！

💡 七、常用命令速查表

📦 八、扩展功能推荐（可选）

📌 九、常见问题排查

1. spawn failed 报错？

• 检查是否安装 Git
• 检查仓库地址是否正确
• 仓库必须是空仓库

2. 部署失败？

• 检查是否配置了 user.name 和 user.email
• 检查仓库分支是否是 main 或 master
• 检查网络是否正常、GitHub 账户是否绑定 SSH 或 HTTPS 正确