个人博客搭建完整教程

最后更新于：2026年3月14日 晚上

个人博客搭建完整教程

基于 Hexo + GitHub Pages + Typora + PicGo 的零基础博客搭建指南

一、前期准备

1.1 工具清单

工具 用途 下载地址
Node.js Hexo 运行环境 https://nodejs.org/
Git 版本控制和部署 https://git-scm.com/
Typora Markdown 编辑器 https://typoraio.cn/
PicGo 图床上传工具 https://github.com/Molunerfinn/PicGo/releases
GitHub 账号 托管博客和图片 https://github.com/

1.2 技术栈说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
┌─────────────────────────────────────────────┐
│                                              │
│  Typora (写作)                               │
│     ↓                                        │
│  PicGo (图片上传)                            │
│     ↓                                        │
│  GitHub (图片存储)                           │
│     ↓                                        │
│  Hexo (生成静态博客)                         │
│     ↓                                        │
│  GitHub Pages (博客托管)                     │
│     ↓                                        │
│  你的博客网站 ✨                             │
│                                              │
└─────────────────────────────────────────────┘

二、安装配置环境

2.1 安装 Node.js

Windows 系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
1. 访问 https://nodejs.org/
2. 下载 LTS 版本（长期支持版）
3. 双击安装包，一路 Next
4. 安装完成后验证：

打开 CMD（Win+R 输入 cmd）
输入：
node -v
npm -v

正常显示版本号即可：
v18.17.0
9.6.7


有基础的小伙伴看可以用nvm进行管理node版本

image-20260314162314048

Mac 系统

1
2
3
4
5
6
# 使用 Homebrew 安装（推荐）
brew install node

# 验证
node -v
npm -v

2.2 安装 Git

Windows 系统

1
2
3
4
5
6
7
8
9
1. 访问 https://git-scm.com/
2. 下载 Windows 版本
3. 安装时全部默认选项
4. 验证：

CMD 中输入：
git --version

显示：git version 2.43.0

image-20260314162414309

配置 Git 用户信息

1
2
3
4
5
6
# 设置用户名和邮箱（替换为你的信息）
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

# 验证配置
git config --global --list

2.3 安装 Hexo

1
2
3
4
5
6
7
8
9
# 全局安装 Hexo CLI
npm install -g hexo-cli

# 验证安装
hexo -v

# 显示类似：
hexo: 7.1.0
hexo-cli: 4.3.1

image-20260314162456068

如果安装慢，配置国内镜像：

1
2
3
4
5
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry

2.4 安装 Typora

这里建议微信搜索 softgj,有破解版本的typora，也可以到我的个人博客资源站看看流程。

image-20260314162617236

1
2
3
4
5
6
7
8
1. 访问 https://typoraio.cn/
2. 下载对应系统版本
3. 安装（一路下一步）
4. 启动 Typora

⚠️ 注意：新版 Typora 收费（89元）
可以下载旧版免费使用：
https://typoraio.cn/windows/dev_release.html

2.5 安装 PicGo

1
2
3
4
1. 访问 https://github.com/Molunerfinn/PicGo/releases
2. 下载最新版：PicGo-Setup-2.5.3.exe
3. 安装到 D:\PicGo（避免中文路径）
4. 启动 PicGo

image-20260314162738569

三、Hexo 博客初始化

3.1 创建博客项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 1. 创建博客文件夹（选择你喜欢的位置）
# 示例：创建在 D 盘
cd D:
mkdir Blog
cd Blog

# 2. 初始化 Hexo 博客
hexo init my-blog
cd my-blog

# 3. 安装依赖
npm install

# 项目结构：
my-blog/
├── _config.yml          # 博客配置文件
├── package.json         # 依赖包信息
├── scaffolds/           # 文章模板
├── source/              # 源文件
│   ├── _posts/         # 博客文章存放处
│   └── about/          # 关于页面
├── themes/              # 主题文件夹
└── public/              # 生成的静态网站

这个有基础的小伙伴可以用vscode打开整个项目，并且下载coplit code插件，登录github实现AI修改整个项目。

3.2 本地预览博客

1
2
3
4
5
6
7
8
9
10
11
12
# 生成静态文件
hexo generate
# 或简写
hexo g

# 启动本地服务器
hexo server
# 或简写
hexo s

# 看到提示：
INFO  Hexo is running at http://localhost:4000/

在浏览器访问：

1
http://localhost:4000

看到默认博客页面说明成功！ 🎉

停止服务器：

1
Ctrl + C

3.3 创建第一篇文章

1
2
3
4
5
6
直接vscode右击在当前目录添加
# 生成文件：
# source/_posts/我的第一篇博客.md

# 编辑文章
# 用 Typora 打开 source/_posts/我的第一篇博客.md

image-20260314163112289

文章模板：

Markdown

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
---
title: 我的第一篇博客
date: 2024-01-15 10:30:00
tags: [Hexo, 博客]
categories: 技术
---

# 欢迎来到我的博客

这是我的第一篇博客文章！

<!-- more -->

## 正文内容

这里是文章正文...

## 插入图片

![示例图片](图片链接)

Front-matter 说明：

YAML

1
2
3
4
5
6
7
8
---
title: 文章标题
date: 发布日期
tags: [标签1, 标签2]        # 标签
categories: 分类            # 分类
description: 文章摘要       # SEO 描述
cover: 封面图片链接         # 文章封面
---

3.4 重新生成并预览

Bash

1
2
3
4
5
6
7
8
# 清除旧文件
hexo clean

# 重新生成
hexo g

# 启动服务
hexo s

访问 http://localhost:4000 查看新文章！

四、GitHub Pages 部署（一下可以问ai）

4.1 创建 GitHub 仓库

步骤 1：新建仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1. 登录 GitHub
2. 点击右上角 + → New repository
3. 填写信息：

┌─────────────────────────────────────┐
│ Repository name *                   │
│ 你的用户名.github.io                 │
│ 例如：zhangsan.github.io            │
├─────────────────────────────────────┤
│ Description (optional)              │
│ My Personal Blog                    │
├─────────────────────────────────────┤
│ ✅ Public                           │
│ （必须公开）                         │
├─────────────────────────────────────┤
│ ☐ Initialize this repository with:  │
│ （什么都不勾选）                     │
└─────────────────────────────────────┘

4. Create repository

⚠️ 重要：仓库名必须是 用户名.github.io

步骤 2：获取仓库地址

1
2
3
4
创建后会显示：
https://github.com/zhangsan/zhangsan.github.io

复制这个地址备用

4.2 配置 SSH 密钥（推荐）

生成 SSH 密钥

1
2
3
4
5
6
7
8
9
10
11
# 1. 打开 Git Bash（Windows）或 Terminal（Mac）

# 2. 生成密钥（替换为你的邮箱）
ssh-keygen -t rsa -C "your_email@example.com"

# 3. 一路回车（使用默认设置）

# 4. 查看公钥
cat ~/.ssh/id_rsa.pub

# 5. 复制显示的内容（以 ssh-rsa 开头）

添加到 GitHub

1
2
3
4
5
6
7
1. GitHub → 右上角头像 → Settings
2. 左侧菜单 → SSH and GPG keys
3. New SSH key
4. 填写：
   Title: My Computer
   Key: 粘贴刚才复制的公钥
5. Add SSH key

验证连接

1
2
3
4
5
ssh -T git@github.com

# 显示：
Hi 你的用户名! You've successfully authenticated...
# 说明成功！

4.3 安装部署插件

1
2
3
# 在博客目录下安装
cd D:\Blog\my-blog
npm install hexo-deployer-git --save

4.4 配置 Hexo 部署

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

1
2
3
4
5
6
7
8
9
10
11
12
13
# 找到 Deployment 部分（在文件最底部）
# 修改为：

deploy:
  type: git
  repository: git@github.com:你的用户名/你的用户名.github.io.git
  branch: main

# 完整示例：
deploy:
  type: git
  repository: git@github.com:zhangsan/zhangsan.github.io.git
  branch: main

⚠️ 注意：

  • 冒号后面有空格
  • 仓库地址替换为你的
  • 新仓库分支是 main，旧仓库可能是 master

4.5 部署到 GitHub

1
2
3
4
5
6
7
8
9
10
11
# 清除旧文件
hexo clean

# 生成静态文件
hexo generate

# 部署到 GitHub
hexo deploy

# 或者三连：
hexo clean && hexo g && hexo d

首次部署会提示输入 GitHub 用户名和密码

部署成功提示：

1
INFO  Deploy done: git

4.6 访问博客

等待 1-2 分钟后访问：

1
2
3
4
https://你的用户名.github.io

例如：
https://zhangsan.github.io

看到博客页面说明部署成功！ 🎉

4.7 配置自定义域名（可选–不是必须，不需要）

购买域名

1
2
3
4
推荐域名商：
- 阿里云：https://wanwang.aliyun.com/
- 腾讯云：https://dnspod.cloud.tencent.com/
- GoDaddy：https://www.godaddy.com/

配置 DNS 解析

1
2
3
4
5
6
7
8
9
10
11
12
1. 进入域名管理控制台
2. 添加 DNS 记录：

类型：CNAME
主机记录：www
记录值：你的用户名.github.io

类型：A
主机记录：@
记录值：185.199.108.153

（GitHub Pages IP 地址）

在 GitHub 配置域名

1
2
3
4
5
1. 进入仓库 Settings
2. Pages → Custom domain
3. 输入你的域名：www.yourdomain.com
4. Save
5. ✅ Enforce HTTPS（勾选）

在 Hexo 配置域名

编辑 _config.yml：

1
2
3
# URL
url: https://www.yourdomain.com
root: /

创建 source/CNAME 文件（无扩展名）：

1
www.yourdomain.com

重新部署：

1
hexo clean && hexo g && hexo d

五、PicGo 图床配置

5.1 创建 GitHub 图床仓库

1
2
3
4
5
6
1. GitHub → New repository
2. 填写：
   Repository name: blog-images
   ✅ Public
   ✅ Add a README file
3. Create repository

5.2 生成 GitHub Token

1
2
3
4
5
6
7
8
9
10
1. GitHub → Settings
2. Developer settings → Personal access tokens
3. Tokens (classic) → Generate new token (classic)
4. 填写：
   Note: PicGo
   Expiration: No expiration
   ✅ repo（全选）
5. Generate token
6. 复制 Token（ghp_xxx...）
   ⚠️ 只显示一次，保存好！

5.3 配置 PicGo

打开 PicGo 配置

1
2
3
1. 启动 PicGo
2. 图床设置 → GitHub 图床
3. 填写配置：

完整配置：

image-20260314163320087

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
┌─────────────────────────────────────────────┐
│ 设定仓库名：                                 │
│ 你的用户名/blog-images                       │
│ 例如：zhangsan/blog-images                  │
├─────────────────────────────────────────────┤
│ 设定分支名：                                 │
│ main                                        │
├─────────────────────────────────────────────┤
│ 设定 Token：                                 │
│ ghp_你的Token                               │
├─────────────────────────────────────────────┤
│ 指定存储路径：                               │
│ blog/images/                                │
│ （按年月分类：blog/{year}/{month}/）         │
├─────────────────────────────────────────────┤
│ 设定自定义域名：                             │
│ https://cdn.jsdelivr.net/gh/用户名/blog-images@main │
│ 例如：                                       │
│ https://cdn.jsdelivr.net/gh/zhangsan/blog-images@main │
└─────────────────────────────────────────────┘

4. 点击「确定」
5. 点击「设为默认图床」

image-20260314163341169

自定义域名说明：

  • 使用 jsDelivr CDN 加速访问
  • 格式：https://cdn.jsdelivr.net/gh/用户名/仓库名@分支名

5.4 PicGo 其他设置

1
2
3
4
5
6
7
8
9
10
1. PicGo 设置 → 设置 Server
   ✅ 设置 Server
   监听端口：36677（默认）
   ✅ 开机自启
   ✅ 时间戳重命名
   ✅ 上传后自动复制 URL

2. 快捷键设置（可选）
   上传剪贴板图片：Ctrl+Shift+P
   上传选择图片：Ctrl+Shift+O

5.5 测试上传

1
2
3
4
5
6
7
8
1. PicGo → 上传区
2. 拖入一张图片
3. 查看上传结果

✅ 成功显示：
https://cdn.jsdelivr.net/gh/zhangsan/blog-images@main/blog/images/xxx.png

4. 复制链接在浏览器打开，能看到图片即可

5.6 解决 SSL 证书错误（如遇到）

上传要访问github，使用vpn学习工具可以实现，所以我们要有vpn工具，没有的可以去我资源站看看

https://xtanguser.github.io/

编辑 PicGo 配置文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Win+R → %APPDATA%\picgo
打开 config.json

添加：
{
  "picBed": {
    ...
  },
  "proxy": "",
  "httpsAgent": {
    "rejectUnauthorized": false
  }
}

保存并重启 PicGo

六、Typora 写作环境

6.1 配置 Typora 图片上传

1
2
3
1. Typora → 文件 → 偏好设置（Ctrl+,）
2. 左侧菜单 → 图像
3. 配置如下：

image-20260314163544234

完整配置：

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
┌─────────────────────────────────────────────┐
│ 图像                                         │
│                                              │
│ 插入图片时...                                 │
│ ┌──────────────────────┐                    │
│ │ 上传图片          ▼│                    │
│ └──────────────────────┘                    │
│                                              │
│ ☑ 对本地位置的图片应用上述规则                │
│ ☑ 对网络位置的图片应用上述规则                │
│ ☑ 优先使用相对路径                           │
│                                              │
│ 上传服务设定                                  │
│ ┌──────────────────────┐                    │
│ │ PicGo(app)        ▼│                    │
│ └──────────────────────┘                    │
│                                              │
│ PicGo 路径：                                 │
│ D:\PicGo\PicGo.exe                          │
│                                              │
│ ☑ 上传前先复制到本地                         │
│ 本地路径：./${filename}.assets              │
│                                              │
│ [验证图片上传选项]                            │
└─────────────────────────────────────────────┘

6.2 验证配置

1
2
3
4
5
6
1. 点击「验证图片上传选项」
2. 等待测试...

✅ 成功显示：
Upload Success:
https://cdn.jsdelivr.net/gh/xxx/blog-images@main/xxx.png

6.3 测试写作流程

新建文章

1
2
# 在博客目录
hexo new "测试图片上传"

使用 Typora 编辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
1. 用 Typora 打开：
   D:\Blog\my-blog\source\_posts\测试图片上传.md

2. 截图（Win+Shift+S）

3. 在 Typora 中粘贴（Ctrl+V）

4. 观察图片是否自动上传

✅ 成功：
![](https://cdn.jsdelivr.net/gh/xxx/blog-images@main/xxx.png)

同时本地保存：
测试图片上传.assets/xxx.png

6.4 Typora 其他配置

偏好设置 → 通用

1
2
☑ 自动保存
☑ 退出时记住上次打开的文件

偏好设置 → 外观

1
2
3
主题：选择喜欢的主题
字体：Microsoft YaHei
字号：16px

偏好设置 → Markdown

1
2
3
4
5
☑ 内联公式
☑ 下标
☑ 上标
☑ 高亮
☑ 图表

七、博客主题美化

7.1 推荐主题（这里都可以用ai助手修改，不用记住配置）

主题 特点 地址
NexT 最流行，简洁优雅 https://github.com/next-theme/hexo-theme-next
Fluid 现代化，Material Design https://github.com/fluid-dev/hexo-theme-fluid
Butterfly 功能丰富，动画炫酷 https://github.com/jerryc127/hexo-theme-butterfly
Matery Material 风格 https://github.com/blinkfox/hexo-theme-matery
Icarus 响应式，专业 https://github.com/ppoffice/hexo-theme-icarus

7.2 安装 NexT 主题（示例）

方法 1：Git 安装（推荐）

1
2
3
4
5
# 进入博客目录
cd D:\Blog\my-blog

# 克隆主题到 themes 目录
git clone https://github.com/next-theme/hexo-theme-next themes/next

方法 2：下载安装

1
2
3
1. 访问 https://github.com/next-theme/hexo-theme-next
2. Code → Download ZIP
3. 解压到 themes/next 目录

7.3 启用主题

编辑博客根目录 _config.yml：

1
2
3
# 找到 theme 配置（第 97 行左右）
# 修改为：
theme: next

清除缓存并预览：

1
2
3
hexo clean
hexo g
hexo s

访问 http://localhost:4000 查看新主题！

7.4 配置主题

编辑 themes/next/_config.yml：

选择主题方案

1
2
3
4
5
# Schemes
# scheme: Muse
# scheme: Mist
# scheme: Pisces
scheme: Gemini    # 取消注释启用

侧边栏设置

1
2
3
4
sidebar:
  position: left    # 位置：left/right
  display: post     # 显示时机：post/always/hide/remove
  width: 300        # 宽度

社交链接

1
2
3
4
5
social:
  GitHub: https://github.com/你的用户名 || fab fa-github
  E-Mail: mailto:your@email.com || fa fa-envelope
  微博: https://weibo.com/xxx || fab fa-weibo
  知乎: https://www.zhihu.com/people/xxx || fab fa-zhihu

头像设置

1
2
3
4
avatar:
  url: /images/avatar.png    # 头像图片
  rounded: true              # 圆形
  rotated: false             # 鼠标悬停旋转

添加头像图片：

1
2
将头像图片放到：
source/images/avatar.png

菜单设置

1
2
3
4
5
6
7
8
9
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  # schedule: /schedule/ || fa fa-calendar
  # sitemap: /sitemap.xml || fa fa-sitemap
  # commonweal: /404/ || fa fa-heartbeat

创建对应页面：

1
2
3
4
5
6
7
8
# 创建关于页面
hexo new page about

# 创建标签页面
hexo new page tags

# 创建分类页面
hexo new page categories

编辑 source/tags/index.md：

1
2
3
4
5
---
title: 标签
type: tags
comments: false
---

编辑 source/categories/index.md：

1
2
3
4
5
---
title: 分类
type: categories
comments: false
---

代码高亮

1
2
3
4
5
6
7
codeblock:
  theme:
    light: default
    dark: stackoverflow-dark
  copy_button:
    enable: true
    show_result: true

阅读进度

1
2
3
4
5
reading_progress:
  enable: true
  position: top    # top/bottom
  color: "#37c6c0"
  height: 3px

返回顶部

1
2
3
4
back2top:
  enable: true
  sidebar: false
  scrollpercent: true

7.5 添加评论功能

使用 Gitalk（基于 GitHub Issues）

1. 创建 GitHub OAuth App

1
2
3
4
5
6
7
8
9
10
1. GitHub → Settings → Developer settings
2. OAuth Apps → New OAuth App
3. 填写：
   Application name: Blog Comments
   Homepage URL: https://你的用户名.github.io
   Authorization callback URL: https://你的用户名.github.io
4. Register application
5. 记录：
   Client ID
   Client Secret

image-20260314171140065

2. 配置主题

编辑 themes/next/_config.yml：

1
2
3
4
5
6
7
8
9
gitalk:
  enable: true
  github_id: 你的GitHub用户名
  repo: 你的用户名.github.io
  client_id: 你的ClientID
  client_secret: 你的ClientSecret
  admin_user: 你的GitHub用户名
  distraction_free_mode: true
  language: zh-CN

7.6 添加搜索功能

1
2
# 安装插件
npm install hexo-generator-searchdb --save

编辑博客 _config.yml：

1
2
3
4
5
6
# 添加到文件末尾
search:
  path: search.xml
  field: post
  content: true
  format: html

编辑 themes/next/_config.yml：

1
2
local_search:
  enable: true

7.7 添加统计功能

字数统计

1
npm install hexo-word-counter --save

编辑 themes/next/_config.yml：

1
2
3
symbols_count_time:
  separated_meta: true
  item_text_total: true

访问统计（不蒜子）

1
2
3
4
5
6
7
8
busuanzi_count:
  enable: true
  total_visitors: true
  total_visitors_icon: fa fa-user
  total_views: true
  total_views_icon: fa fa-eye
  post_views: true
  post_views_icon: far fa-eye

八、日常写作发布流程

8.1 完整工作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
┌────────────────────────────────────────────┐
│                                             │
│  1. 创建文章                                 │
│     hexo new "文章标题"                      │
│         ↓                                   │
│  2. Typora 编辑                              │
│     - 写作内容                               │
│     - 粘贴图片（自动上传）                    │
│         ↓                                   │
│  3. 本地预览                                 │
│     hexo clean && hexo g && hexo s          │
│     访问 http://localhost:4000              │
│         ↓                                   │
│  4. 发布到 GitHub                            │
│     hexo deploy                             │
│         ↓                                   │
│  5. 访问博客                                 │
│     https://你的用户名.github.io             │
│                                             │
└────────────────────────────────────────────┘

8.2 详细步骤

Step 1：新建文章

1
2
3
4
5
6
7
8
9
10
# 进入博客目录
cd D:\Blog\my-blog

# 创建新文章
hexo new "Vue 3 学习笔记"

# 或指定布局
hexo new post "Vue 3 学习笔记"
hexo new page "关于我"
hexo new draft "草稿文章"

生成文件：

1
source/_posts/Vue-3-学习笔记.md

Step 2：编辑文章

用 Typora 打开文章：

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
28
29
30
31
32
33
34
35
36
37
38
---
title: Vue 3 学习笔记
date: 2024-01-15 14:30:00
tags: 
  - Vue
  - 前端
categories: 
  - 技术
  - 前端开发
description: Vue 3 核心特性学习总结
cover: https://xxx.com/cover.jpg
---

# Vue 3 新特性

这是文章摘要，会显示在首页...

<!-- more -->

## Composition API

详细内容...

### 响应式原理

![响应式示意图](图片)  ← 直接粘贴，自动上传

## 代码示例

```javascript
import { ref, reactive } from 'vue'

const count = ref(0)
const state = reactive({ name: 'Vue 3' })
```

## 总结

Front-matter 完整参数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
title: 文章标题                    # 必填
date: 2024-01-15 14:30:00        # 创建日期
updated: 2024-01-16 10:00:00     # 更新日期
tags:                            # 标签（数组）
  - 标签1
  - 标签2
categories:                      # 分类（层级）
  - 一级分类
  - 二级分类
description: 文章描述              # SEO 描述
keywords: 关键词1, 关键词2        # SEO 关键词
top: true                        # 置顶
cover: 封面图片链接                # 封面图
comments: true                   # 开启评论
permalink: custom-url            # 自定义链接
---

Step 3：插入图片

方法 1：截图粘贴（最常用）

1
2
3
4
5
6
7
1. 截图（Win+Shift+S）
2. Typora 中 Ctrl+V
3. 自动上传到图床
4. 本地保存备份到 .assets 文件夹

生成：
![](https://cdn.jsdelivr.net/gh/xxx/blog-images@main/xxx.png)

方法 2：拖拽本地图片

1
2
1. 从文件夹拖图片到 Typora
2. 自动上传

方法 3：手动插入

1
![图片描述](https://xxx.com/image.png)

Step 4：本地预览

1
2
3
4
5
6
7
8
9
10
11
# 清除缓存
hexo clean

# 生成静态文件
hexo generate

# 启动本地服务
hexo server

# 简写三连
hexo clean && hexo g && hexo s

访问预览：

1
http://localhost:4000

检查：

  • 文章标题正确
  • 标签分类显示
  • 图片正常加载
  • 代码高亮正常
  • 排版无问题

停止服务：

1
Ctrl + C

Step 5：部署到 GitHub

1
2
3
4
5
6
7
# 清除 + 生成 + 部署
hexo clean && hexo g && hexo d

# 或分步执行
hexo clean
hexo generate
hexo deploy

部署成功提示：

1
INFO  Deploy done: git

等待 1-2 分钟后访问：

1
https://你的用户名.github.io

8.3 常用命令速查

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
# 新建
hexo new "title"              # 新建文章
hexo new page "about"         # 新建页面
hexo new draft "draft"        # 新建草稿

# 生成
hexo generate                 # 生成静态文件
hexo g                        # 简写

# 服务器
hexo server                   # 启动服务器
hexo s                        # 简写
hexo s -p 5000               # 指定端口
hexo s --draft               # 显示草稿

# 部署
hexo deploy                   # 部署
hexo d                        # 简写

# 清理
hexo clean                    # 清除缓存

# 组合命令
hexo clean && hexo g && hexo d    # 一键部署
hexo clean && hexo g && hexo s    # 清除并预览

8.4 草稿管理

创建草稿

1
2
3
4
hexo new draft "未完成的文章"

# 草稿位置：
source/_drafts/未完成的文章.md

预览草稿

Bash

1
hexo server --draft

发布草稿

1
2
3
hexo publish draft "未完成的文章"

# 将文章从 _drafts 移到 _posts

8.5 文件管理建议

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
my-blog/
├── source/
│   ├── _posts/              # 已发布文章
│   │   ├── 2024-01-Vue学习笔记.md
│   │   ├── 2024-01-Vue学习笔记.assets/  # 图片备份
│   │   ├── 2024-02-React入门.md
│   │   └── 2024-02-React入门.assets/
│   ├── _drafts/            # 草稿
│   │   └── 待完成.md
│   ├── about/              # 关于页面
│   ├── tags/               # 标签页面
│   ├── categories/         # 分类页面
│   └── images/             # 全局图片
│       └── avatar.png      # 头像
└── themes/
    └── next/

九、常见问题解决

9.1 部署问题

❌ 问题：hexo d 报错 Permission denied

原因： SSH 密钥配置问题

解决：

1
2
3
4
5
# 1. 检查 SSH 连接
ssh -T git@github.com

# 2. 如果失败，重新配置 SSH
# 参考 4.2 节

❌ 问题：GitHub Pages 404

原因： 仓库名不对或未启用 Pages

解决：

1
2
3
4
5
1. 确认仓库名是：用户名.github.io
2. 进入仓库 Settings → Pages
3. Source 选择：Deploy from a branch
4. Branch 选择：main / (root)
5. Save

❌ 问题：博客样式丢失

原因： _config.yml 中 url 配置错误

解决：

编辑 _config.yml：

1
2
3
# URL
url: https://你的用户名.github.io
root: /

如果使用自定义域名：

1
2
url: https://www.yourdomain.com
root: /

重新部署：

1
hexo clean && hexo g && hexo d

9.2 图片问题

❌ 问题：图片上传失败 404

参考第五章第 5.6 节解决 SSL 证书问题

❌ 问题：jsDelivr CDN 国内无法访问

原因： jsDelivr 在国内被墙

解决方案：

方法 1：使用国内 CDN

PicGo 自定义域名改为：

1
2
3
4
https://fastly.jsdelivr.net/gh/用户名/仓库名@main

或使用 GitHub 原始链接：
https://raw.githubusercontent.com/用户名/仓库名/main

方法 2：换用国内图床

  • 阿里云 OSS
  • 腾讯云 COS
  • 七牛云
  • SM.MS

方法 3：自建图床

使用 Vercel + GitHub 搭建：

1
2
3
1. Fork Cloudflare Workers 图床项目
2. 部署到 Vercel
3. PicGo 配置自定义域名为 Vercel 域名

❌ 问题：本地图片显示但部署后 404

原因： 图片路径大小写不一致

解决：

1
2
3
4
5
Windows 不区分大小写，Linux 区分

确保：
- 图片文件名统一小写
- Markdown 引用路径与实际文件名一致

9.3 主题问题

❌ 问题：主题更新后配置丢失

解决： 使用主题配置文件覆盖

创建 _config.next.yml（博客根目录）：

1
2
3
4
5
6
7
8
# 复制 themes/next/_config.yml 的内容到这里
# 此文件优先级更高，主题更新不会覆盖

scheme: Gemini
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  ...

❌ 问题：第三方插件不生效

检查：

1
2
3
4
5
6
7
1. 插件是否安装：
   npm list --depth 0

2. _config.yml 配置是否正确

3. 清除缓存重试：
   hexo clean && hexo g && hexo s

9.4 性能优化

问题：博客加载慢

解决方案：

1. 图片压缩

1
2
# 安装压缩插件
npm install hexo-image-minifier --save

_config.yml：

1
2
3
4
5
6
7
image_minifier:
  enable: true
  interlaced: false
  multipass: false
  optimizationLevel: 2
  pngquant: false
  progressive: false

2. 启用 CDN

themes/next/_config.yml：

1
2
3
vendors:
  jquery: https://cdn.jsdelivr.net/npm/jquery@3/dist/jquery.min.js
  font_awesome: https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/css/all.min.css

3. 代码压缩

1
npm install hexo-all-minifier --save

_config.yml：

1
all_minifier: true

十、进阶优化

10.1 SEO 优化

安装 SEO 插件

1
2
3
4
5
6
# 生成 sitemap
npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-sitemap --save

# 自动 nofollow
npm install hexo-autonofollow --save

配置 sitemap

_config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
# Sitemap
sitemap:
  path: sitemap.xml

baidusitemap:
  path: baidusitemap.xml

# nofollow
nofollow:
  enable: true
  exclude:
    - exclude1.com
    - exclude2.com

提交搜索引擎

Google Search Console

1
2
3
4
5
1. 访问 https://search.google.com/search-console
2. 添加资源：https://你的用户名.github.io
3. 验证所有权（HTML 文件验证）
4. 提交 sitemap：
   https://你的用户名.github.io/sitemap.xml

百度站长平台

1
2
3
4
5
1. 访问 https://ziyuan.baidu.com/
2. 用户中心 → 站点管理 → 添加网站
3. 验证站点
4. 链接提交 → sitemap：
   https://你的用户名.github.io/baidusitemap.xml

10.2 自动化部署

使用 GitHub Actions

创建 .github/workflows/deploy.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
28
29
30
31
name: Deploy Hexo

on:
  push:
    branches:
      - source  # 源码分支

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: main

使用方式：

1
2
3
4
5
6
7
# 创建 source 分支存放源码
git checkout -b source
git add .
git commit -m "source"
git push origin source

# 推送到 source 分支后自动部署到 main 分支

10.3 多设备同步

方案：使用 Git 管理源码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 1. 初始化 Git（如果还没有）
git init

# 2. 添加 .gitignore
cat > .gitignore << EOF
.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
EOF

# 3. 提交到 source 分支
git checkout -b source
git add .
git commit -m "blog source"
git push origin source

# 4. 在新设备克隆
git clone -b source https://github.com/用户名/用户名.github.io.git
cd 用户名.github.io
npm install

日常使用：

1
2
3
4
5
6
7
8
# 设备 A 写作后
git add .
git commit -m "new post"
git push

# 设备 B 同步
git pull
npm install  # 如果有新依赖

10.4 备份方案

自动备份脚本

创建 backup.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/bin/bash

# 备份目录
BACKUP_DIR="D:/BlogBackup"
DATE=$(date +%Y%m%d)

# 创建备份
echo "开始备份..."
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/blog-$DATE.tar.gz \
  --exclude='node_modules' \
  --exclude='public' \
  --exclude='.deploy_git' \
  .

echo "备份完成: blog-$DATE.tar.gz"

# 保留最近 7 天的备份
find $BACKUP_DIR -name "blog-*.tar.gz" -mtime +7 -delete

Windows 使用批处理：

backup.bat：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@echo off
set BACKUP_DIR=D:\BlogBackup
set DATE=%date:~0,4%%date:~5,2%%date:~8,2%

echo 开始备份...
if not exist %BACKUP_DIR% mkdir %BACKUP_DIR%

7z a -tzip %BACKUP_DIR%\blog-%DATE%.zip ^
  -xr!node_modules ^
  -xr!public ^
  -xr!.deploy_git ^
  *

echo 备份完成

10.5 评论系统升级

使用 Waline（推荐）

特点：

  • 基于 Vercel 免费部署
  • 支持 Markdown
  • 邮件通知
  • 后台管理

部署步骤：

1
2
3
4
5
1. 访问 https://waline.js.org/
2. 点击「快速开始」
3. Deploy to Vercel
4. 连接 GitHub 仓库
5. 获取部署后的域名

配置主题：

themes/next/_config.yml：

1
2
3
4
5
6
7
8
9
10
waline:
  enable: true
  serverURL: https://你的域名.vercel.app
  placeholder: 欢迎留言...
  avatar: mp
  meta: [nick, mail, link]
  pageSize: 10
  lang: zh-CN
  visitor: true
  comment_count: true

🎯 总结：完整工作流程

初次搭建

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
# 1. 安装环境
安装 Node.js, Git, Typora, PicGo

# 2. 初始化博客
hexo init my-blog
cd my-blog
npm install

# 3. 配置 GitHub 仓库
创建 用户名.github.io 仓库
配置 SSH 密钥

# 4. 配置 Hexo
编辑 _config.yml

# 5. 安装主题
git clone 主题仓库 themes/主题名

# 6. 配置图床
创建 blog-images 仓库
配置 PicGo
配置 Typora

# 7. 首次部署
hexo clean && hexo g && hexo d

日常写作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 创建文章
hexo new "文章标题"

# 2. Typora 编辑
打开 source/_posts/文章.md
写作 + 粘贴图片（自动上传）

# 3. 本地预览
hexo clean && hexo g && hexo s
访问 http://localhost:4000

# 4. 发布
hexo deploy
访问 https://用户名.github.io

快速命令备忘

1
2
3
4
5
6
7
8
9
10
11
12
# 新建
hexo new "title"

# 预览
hexo clean && hexo g && hexo s

# 部署
hexo clean && hexo g && hexo d

# 一键操作（创建别名）
alias hd="hexo clean && hexo g && hexo d"
alias hs="hexo clean && hexo g && hexo s"

📚 参考资源

🎉 恭喜！

你已经完成了个人博客的搭建！

下一步：

  • ✍️ 开始写作第一篇文章
  • 🎨 美化主题样式
  • 🔧 添加更多功能
  • 📈 优化 SEO
  • 🚀 分享你的博客

记住：内容才是王道，坚持写作！ 💪

有任何问题随时查阅本教程或搜索相关文档。祝你博客之旅愉快！🌟

资源
#Hexo #GitHub Pages #Typora #PicGo
个人博客搭建完整教程
https://xtanguser.github.io/2026/03/14/个人博客搭建完整教程/
作者
小唐
发布于
2026年3月14日
许可协议