这是通过 GitHub Actions 自动部署的博客，记录我从零搭建个人博客的完整过程，包括遇到的各种坑和解决方案。

一、为什么选择 Hexo + GitHub Pages

在搭建个人博客时，我对比了几个主流方案：

  • WordPress：需要服务器，维护成本高
  • VuePress：基于 Vue，文档型博客
  • Hexo：成熟稳定，主题丰富，部署简单
  • Hugo：速度快，但学习成本较高

最终选择 Hexo + GitHub Pages，原因：

  1. 免费托管
  2. GitHub Actions 自动部署
  3. 主题丰富（NexT、Even 等）
  4. 社区活跃，问题容易解决

二、环境准备

1. 安装 Node.js

从 Node.js 官网 下载安装。

2. 安装 Hexo

1
npm install -g hexo-cli

3. 初始化博客

1
2
3
hexo init my-blog
cd my-blog
npm install

三、遇到的坑（重点！）

搭建过程中遇到了很多问题，我将详细的踩坑笔记整理到了单独的文章中：

📝 详细踩坑笔记：Hexo GitHub Pages 踩坑笔记

主要遇到的坑包括：

  1. Hexo 7 的破坏性更新 - 需要手动安装 sass、ejs 渲染器等依赖
  2. GitHub Actions 部署权限错误 - 需要配置 permissions: contents: write
  3. CSS 文件 404 错误 - 需要安装 Stylus 渲染器
  4. 主题切换的坑 - 使用 Git Submodule 管理主题是最佳实践
  5. CI/CD 中 SCSS 编译失败 - 需要配置编译脚本
  6. 子模块提交找不到 - 不要修改第三方主题仓库的代码
  7. 双仓库部署的权限噩梦 - 最终选择同仓库不同分支的方案

建议阅读详细的踩坑笔记，里面包含了完整的问题分析和解决方案。

四、完整的工作流配置

.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
name: Hexo Auto Deploy

on:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: true  # 关键：克隆子模块

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

      - name: Install dependencies
        run: npm install

      - name: Clean and Build
        run: |
          npx hexo clean
          npm run build

      - name: Deploy to gh-pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages
          force_orphan: true

五、主题选择：NexT vs Even

NexT 主题

  • 功能丰富，可定制项多
  • 样式相对复杂
  • 适合内容较多的博客

Even 主题

  • 简洁现代，专注阅读体验
  • 响应式设计优秀
  • 适合技术博客

最终选择： Even 主题，简洁就是美。

六、博客配置

主配置 _config.yml

1
2
3
4
5
6
title: 技术笔记
subtitle: 记录开发历程
description: 个人技术博客
author: homleening
url: https://homleening.github.io
theme: even

主题配置 _config.even.yml

1
2
3
4
5
6
7
8
9
10
# 头像和图标
favicon: /images/favicon.ico
avatar: /images/avatar.png

# 菜单
menu:
  首页: /
  归档: /archives/
  标签: /tags/
  分类: /categories/

七、创建标签和分类页面

Hexo 不会自动生成标签和分类页面，需要手动创建：

标签页 source/tags/index.md：

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

分类页 source/categories/index.md：

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

八、写作技巧

文章 Front-matter

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 文章标题
date: 2026-06-10
tags:
  - 标签1
  - 标签2
categories:
  - 分类
description: 文章描述
---

文章内容使用 Markdown 语法...

代码高亮

1
Console.WriteLine("Hello World");
1
2
def hello():
    print("Hello, World!")
1
console.log("Hello World");

九、总结

搭建这个博客虽然遇到很多坑，但收获满满：

  1. 理解了 Hexo 的工作原理：从 Markdown 到静态 HTML
  2. 掌握了 Git Submodule：优雅管理第三方依赖
  3. 熟悉了 GitHub Actions：自动化部署流程
  4. 学会了排查问题：日志分析、错误定位

十、参考资料

持续更新中…

版权声明

本文章采用 CC BY-NC-SA 4.0 知识共享协议 开源。

  1. 允许个人学习、非商业转载；
  2. 禁止未经授权 AI 批量爬取、模型训练、洗稿商用；
  3. 转载必须标注原文链接与作者出处。