Hexo + GitHub Pages

1、准备工作 - 安装必要软件

步骤1：安装 Node.js

Node.js 是运行 Hexo 的必要环境。

  1. 打开浏览器，访问：https://nodejs.org/
  2. 下载 LTS（长期支持版） 版本
  3. 双击下载的安装包，一路点击”下一步”完成安装
  4. 验证安装：
    • 按 Win + R，输入 cmd，回车打开命令提示符
    • 输入命令：node -v
    • 如果显示版本号（如 v20.11.0），说明安装成功

步骤2：安装 Git

Git 是版本控制工具，用于上传博客到 GitHub。

  1. 访问：https://git-scm.com/downloads
  2. 选择 Windows 版本下载
  3. 安装时保持默认选项，一路”下一步”
  4. 验证安装：
    • 在命令提示符输入：git --version
    • 显示版本号即成功

步骤3：注册 GitHub 账号

GitHub 用于托管你的博客代码。

  1. 访问：https://github.com/
  2. 点击右上角 Sign up（注册）
  3. 填写邮箱、密码、用户名
  4. 完成邮箱验证

步骤4：创建 GitHub 仓库

  1. 登录 GitHub 后，点击右上角 + 号，选择 New repository
  2. 仓库名称填写：你的用户名.github.io（例如：zhangsan.github.io）
  3. 选择 Public（公开）
  4. 勾选 Add a README file
  5. 点击 Create repository

2、 安装和配置 Hexo

步骤1：安装 Hexo

打开命令提示符，输入以下命令：

1
2
3
4
5
# 安装 Hexo
npm install -g hexo-cli

# 等待安装完成后，验证
hexo -v

步骤2：创建博客项目

1
2
3
4
5
6
7
8
9
10
# 创建一个博客文件夹（放在你想保存的位置）
# 例如放在 D 盘
cd D:
hexo init myblog

# 进入博客目录
cd myblog

# 安装依赖
npm install

步骤3：本地预览博客

1
2
3
4
5
# 生成静态文件
hexo generate

# 启动本地服务器
hexo server

打开浏览器，访问：http://localhost:4000

你将看到 Hexo 的默认博客页面！

3、部署到 GitHub Pages

步骤1：安装部署插件

在命令提示符中：

1
2
cd D:\myblog
npm install hexo-deployer-git --save

步骤2：配置 _config.yml

  1. 用记事本或 VS Code 打开 D:\myblog\_config.yml 文件
  2. 找到文件末尾的 deploy: 部分，修改为：
1
2
3
4
deploy:
  type: git
  repo: https://github.com/你的用户名/你的用户名.github.io.git
  branch: main

注意：将”你的用户名”替换为你的 GitHub 用户名

步骤3：配置 Git 用户信息

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

步骤4：部署到 GitHub

1
2
3
4
cd D:\myblog
hexo clean
hexo generate
hexo deploy

第一次部署时会弹出 GitHub 登录窗口，按提示登录即可。

4、 访问你的博客

部署完成后，访问：https://你的用户名.github.io

你的博客已经上线了！

5、 日常使用 - 如何写文章

创建新文章

1
2
cd D:\myblog
hexo new "我的第一篇文章"

这会在 source/_posts/ 目录下创建一个 Markdown 文件。

编辑文章

用记事本或编辑器打开 source/_posts/我的第一篇文章.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
title: 我的第一篇文章
date: 2026-04-08 10:00:00
tags:
  - 教程
categories:
  - 生活
---

这里是文章正文内容...

## 标题一

正文内容...

### 标题二

更多内容...

发布更新

1
2
3
4
cd D:\myblog
hexo clean
hexo generate
hexo deploy

6、 更换博客主题

Hexo 有很多漂亮的主题，以 Next 主题为例：

1
2
cd D:\myblog
npm install hexo-theme-next

修改 _config.yml 文件：

1
theme: next

重新生成部署即可。

7、SSH方式部署（部署失败的话）

步骤 1：生成 SSH 密钥（如果还没有）

1
ssh-keygen -t ed25519 -C "your_email@example.com"

一路回车（默认路径即可）。

步骤 2：将公钥添加到 GitHub

  1. 打开文件：C:\Users\<你的用户名>\.ssh\id_ed25519.pub

  2. 复制全部内容

  3. 访问 https://github.com/settings/keys

  4. 点击

    New SSH key

    • Title: My Blog Deploy Key（随便写）
    • Key type: Authentication Key
    • 粘贴公钥内容

  5. 点击 Add SSH key

步骤 3：测试 SSH 连接

1
ssh -T git@github.com

你应该看到：

1
Hi changlan-a! You've successfully authenticated...

⚠️ 如果提示“connection timed out”，说明 SSH 也被阻。可尝试 SSH over HTTPS（端口 443）（见文末备选方案）。

步骤 4：修改 Hexo 配置为 SSH 地址

编辑 _config.yml：

1
2
3
4
1  deploy:
2  	type: git
3 	repo: git@github.com:你的GitHub用户名/你的GitHub用户名.github.io.git  # ← 改成这个！
4	branch: master

步骤 5：重新部署

1
2
3
hexo clean
hexo generate
hexo deploy