从零搭建 Hexo + NexT 个人博客：双端自动部署全记录

发表于 分类于 阅读次数： 本文字数： 2.1k 阅读时长 ≈ 8 分钟
记录从零搭建 Hexo 博客的全过程，包括环境配置、主题定制、CI/CD 自动部署，以及在 VPN 网络环境下遇到的各种坑和解决方案。

前言

作为一个程序员，拥有一个属于自己的技术博客一直是我的愿望。经过调研，我选择了 Hexo + NexT 这套经典组合，并实现了 GitHub Pages + Cloudflare Pages 双端自动部署。

本文将完整记录整个搭建过程，重点分享遇到的问题和解决方案，希望能帮到有同样需求的朋友。

一、技术选型

项目 选择 理由
静态博客框架 Hexo 6.3.0 生态成熟，插件丰富，Markdown 写作
主题 NexT 8.27.0 最流行的 Hexo 主题，简洁优雅
主题风格 Gemini 卡片式布局，信息密度适中
代码托管 GitHub 私有仓库 源码安全，免费无限私有仓库
部署平台 GitHub Pages + Cloudflare Pages 双端冗余，Cloudflare 无限带宽
CI/CD GitHub Actions 与 GitHub 无缝集成，免费额度充足
图床 阿里云 OSS 国内访问快，有免费额度

二、环境准备

2.1 基础软件

1
2
3
4
5
6
7
8
# 检查 Node.js（推荐 LTS 版本）
node -v   # v24.15.0

# 检查 Git
git --version   # git version 2.54.0

# 检查 npm
npm -v   # 11.12.1

2.2 安装 Hexo CLI

1
npm install -g hexo-cli

2.3 初始化项目

这里遇到了第一个坑：hexo init 要求目标目录必须为空，而我的工作目录已有文件。

解决方案：在临时目录初始化，再复制回来。

1
2
3
4
5
6
7
8
9
10
# 克隆 Hexo 模板到临时目录
# 注意：如果 GitHub 访问超时，可以用 Gitee 镜像
git clone https://gitee.com/hexojs/hexo-starter.git _hexo_temp --depth 1

# 进入临时目录安装依赖（使用国内镜像加速）
cd _hexo_temp
npm install --registry=https://registry.npmmirror.com

# 将文件复制到博客根目录
# 复制 _config.yml、package.json、scaffolds/、source/、themes/ 等

网络提示：如果你的网络环境无法直接访问 GitHub，npm 安装时可以使用 --registry=https://registry.npmmirror.com 切换到国内镜像源。

三、主题配置

3.1 安装 NexT 主题

1
npm install hexo-theme-next

3.2 修改主配置 _config.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
# 站点信息
title: 我的博客
subtitle: '记录技术与生活'
description: '个人技术博客，分享编程心得与生活感悟'
author: 你的名字
language: zh-CN
timezone: 'Asia/Shanghai'

# 站点 URL
url: https://你的用户名.github.io

# 切换主题
theme: next

3.3 创建 NexT 配置 _config.next.yml

NexT 推荐使用独立的 _config.next.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
# 选择风格
scheme: Gemini

# 菜单
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  categories: /categories/ || fa fa-th
  tags: /tags/ || fa fa-tags
  about: /about/ || fa fa-user

# 代码高亮（必须配置，否则会报错！）
codeblock:
  theme:
    light: default
    dark: stackoverflow-dark
  copy_button:
    enable: true

# 目录 TOC
toc:
  enable: true
  number: true

# 阅读统计
post_wordcount:
  wordcount: true
  min2read: true

踩坑记录：如果没有配置 codeblock.theme.light/dark，hexo generate 会报 ENOENT: no such file or directory, open '' 错误。此外还需要单独安装 highlight.js：

1
npm install highlight.js

3.4 创建必要页面

1
2
3
hexo new page about       # 关于页面
hexo new page categories  # 分类页面
hexo new page tags         # 标签页面

然后修改各页面的 front-matter：

1
2
3
4
5
6
7
8
9
10
11
# source/categories/index.md
---
title: 分类
type: categories
---

# source/tags/index.md
---
title: 标签
type: tags
---

3.5 安装功能插件

1
2
3
4
5
6
7
8
# 本地搜索
npm install hexo-generator-search

# SEO Sitemap
npm install hexo-generator-sitemap

# 字数统计
npm install hexo-word-counter

在 _config.yml 末尾添加：

1
2
3
4
5
6
7
8
9
10
11
# 搜索
search:
  path: search.xml
  field: post
  content: true

# Sitemap
sitemap:
  path:
    - sitemap.xml
    - sitemap.txt

3.6 本地预览

1
hexo clean && hexo generate && hexo server

浏览器打开 http://localhost:4000，看到博客正常显示就可以进入下一步了。

四、GitHub 仓库配置

4.1 创建两个仓库

仓库 类型 用途
my-blog-source 私有 存放博客源码（Markdown 等）
你的用户名.github.io 公开 GitHub Pages 部署仓库

为什么源码要私有？ 因为博客源码包含配置文件、未发布的草稿等，不适合公开。而部署产物（HTML/CSS/JS）是公开的。

4.2 SSH 密钥配置

1
2
3
4
5
# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "your-email@example.com"

# 查看公钥，复制到 GitHub → Settings → SSH keys
cat ~/.ssh/id_ed25519.pub

4.3 关联远程仓库

1
2
3
4
cd 你的博客目录
git init
git branch -M main
git remote add origin git@github.com:你的用户名/my-blog-source.git

五、自动部署（核心部分）

这是整个搭建过程中最折腾的部分，经历了多次方案迭代。

5.1 部署方案演进

1
2
3
4
5
6
7
8
9
10
方案一：SSH Deploy Key + peaceiris/actions-gh-pages
  → 问题：VPN 环境下 SSH 连接不稳定

方案二：PAT (Personal Access Token) + peaceiris/actions-gh-pages
  → 问题：Secret 识别失败

方案三：GitHub 官方 actions/deploy-pages
  → 问题：免费账户的私有仓库不支持 GitHub Pages

最终方案：直接 git push 到公开仓库 ✅

5.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
32
33
34
35
36
37
38
39
40
name: Deploy Blog

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy-github-pages:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npx hexo generate

      - name: Deploy to GitHub Pages
        run: |
          cd public
          git init
          git checkout -b main
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "deploy: ${{ github.event.head_commit.message }}"
          git push -f https://x-access-token:${{ secrets.GH_TOKEN }}@github.com/你的用户名/你的用户名.github.io.git main

5.3 配置 GitHub Secrets

在 my-blog-source 仓库的 Settings → Secrets → Actions 中添加：

Secret 名称 说明 获取方式
GH_TOKEN GitHub Personal Access Token Settings → Developer settings → Personal access tokens → 创建 Classic Token，勾选 repo 权限

5.4 配置 GitHub Pages

在 你的用户名.github.io 仓库的 Settings → Pages 中：

  • Source: Deploy from a branch
  • Branch: main / (root)

六、Cloudflare Pages 配置

Cloudflare Pages 的接入比 GitHub Pages 简单得多：

  1. 登录 Cloudflare Dashboard
  2. 左侧菜单 → Workers & Pages
  3. 点击 Create → Pages → Connect to Git
  4. 选择你的 my-blog-source 仓库
  5. 配置构建命令：npx hexo generate
  6. 输出目录：public

Cloudflare 会自动监听 GitHub 推送并构建部署，分配一个 *.pages.dev 的子域名。

优势：Cloudflare Pages 带宽完全免费无限制，作为 GitHub Pages 的冗余备份非常合适。

七、遇到的问题汇总

问题 1：hexo init 要求空目录

现象：hexo init . 报错 FATAL target not empty

原因：Hexo 初始化要求目标目录为空

解决：在临时目录初始化后复制文件回来

问题 2：GitHub 连接超时

现象：fatal: unable to access 'https://github.com/...' after 21095 ms

原因：国内网络无法直接访问 GitHub

解决：

1
2
3
4
5
6
7
8
9
# 使用 Gitee 镜像克隆
git clone https://gitee.com/hexojs/hexo-starter.git

# npm 使用国内镜像
npm install --registry=https://registry.npmmirror.com

# 配置 Git 代理（如果使用 VPN）
git config --global http.proxy http://127.0.0.1:7892
git config --global https.proxy http://127.0.0.1:7892

问题 3：代码高亮报错

现象：hexo generate 报 ENOENT: no such file or directory, open ''

原因：NexT 主题需要 highlight.js 和 codeblock.theme 配置

解决：

1
npm install highlight.js

在 _config.next.yml 中添加：

1
2
3
4
codeblock:
  theme:
    light: default
    dark: stackoverflow-dark

问题 4：SSH 连接被拒绝

现象：ssh -T git@github.com 报 Connection closed 或 Permission denied

原因：VPN 环境下 SSH 端口 22 被阻断

解决：配置 SSH 走 443 端口：

1
2
3
4
# 编辑 ~/.ssh/config
Host github.com
  Hostname ssh.github.com
  Port 443

问题 5：私有仓库不支持 GitHub Pages

现象：actions/configure-pages 报 Get Pages site failed

原因：GitHub 免费账户的私有仓库不支持 Pages 功能

解决：使用私有仓库存放源码，通过 Actions 将构建产物推送到单独的公开仓库

问题 6：git push 报 refspec 不匹配

现象：error: src refspec main does not match any

原因：git init 默认创建 master 分支，但远程期望 main 分支

解决：在 push 前切换分支：

1
git checkout -b main

八、日常写作流程

搭建完成后，日常写博客只需要三步：

1
2
3
4
5
6
7
8
9
# 1. 写文章
hexo new "我的第一篇文章"
# 然后编辑 source/_posts/我的第一篇文章.md

# 2. 本地预览
hexo clean && hexo s

# 3. 发布
git add . && git commit -m "add: 我的第一篇文章" && git push

推送后 GitHub Actions 会自动构建并部署到 GitHub Pages，Cloudflare Pages 也会同步更新。

九、后续规划

  • 博客基础搭建
  • NexT 主题定制
  • GitHub Pages 自动部署
  • Cloudflare Pages 双端部署
  • Gitalk 评论系统（需要 GitHub OAuth App）
  • 阿里云 OSS 图床配置
  • 自定义域名绑定
  • 百度/Google 收录

总结

整个搭建过程最大的挑战不是技术本身，而是网络环境带来的各种限制。在 VPN 环境下，无论是 SSH 还是 HTTPS 都需要额外配置代理，这是很多教程不会提到的。

最终的架构是：私有仓库存源码 → GitHub Actions 构建 → 推送到公开仓库 → GitHub Pages 提供服务，同时 Cloudflare Pages 作为冗余。这套方案免费、稳定、且支持跨设备同步。

希望这篇文章对你有帮助！如果遇到问题，欢迎在评论区交流。