前言

在当今的技术博客时代，Hexo 作为一款快速、简洁且高效的静态博客框架，深受开发者喜爱。而 GitHub Pages 则为我们提供了免费的静态网站托管服务。将两者结合，通过 GitHub Actions 实现自动部署，不仅能让我们专注于内容创作，还能享受到自动化部署带来的便利。

本文将详细介绍如何使用 GitHub Actions 自动部署 Hexo 博客，从环境搭建到最终部署，一步一步带您完成整个流程。

GitHub Actions 部署流程

准备工作

在开始之前，您需要准备以下工具和环境：

必备工具

  • Git：版本控制工具
  • Node.js：JavaScript 运行环境（推荐 LTS 版本）
  • npm：Node.js 包管理器
  • GitHub 账号：用于仓库托管和 Pages 服务

检查环境

打开终端，执行以下命令检查工具是否安装成功：

1
2
3
4
5
6
7
8
9
10
11
\# 检查 Git 版本

git --version

\# 检查 Node.js 版本

node -v

\# 检查 npm 版本

npm -v

Git 命令行界面

环境搭建

1. 安装 Hexo 框架

首先，全局安装 Hexo CLI：

1
npm install -g hexo-cli

2. 初始化博客项目

创建一个新的文件夹作为博客根目录，并初始化 Hexo 项目：

1
2
3
4
5
6
7
8
9
10
11
\# 创建博客目录

mkdir my-blog

cd my-blog

\# 初始化 Hexo 项目

hexo init

npm install

3. 本地预览博客

执行以下命令启动本地服务器，预览博客效果：

1
hexo s

打开浏览器，访问 http://localhost:4000 即可看到默认的 Hexo 博客界面。

Hexo 博客界面

创建 GitHub 仓库

1. 创建两个仓库

为了实现自动部署，我们需要创建两个 GitHub 仓库：

  • 源码仓库：用于存储 Hexo 博客的源代码（Markdown 文章、主题配置等）
  • 部署仓库：用于 GitHub Pages 部署，命名格式为 username.github.io

2. 配置 Git 远程仓库

在本地博客目录中，执行以下命令配置 Git 远程仓库：

1
2
3
4
5
6
7
\# 初始化 Git 仓库

git init

\# 添加远程仓库地址

git remote add origin https://github.com/your-username/my-blog.git

3. 创建 .gitignore 文件

为了避免上传不必要的文件，创建 .gitignore 文件：

1
2
3
\# 编辑 .gitignore 文件

nano .gitignore

添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
.DS\_Store

Thumbs.db

db.json

\*.log

node\_modules/

public/

.deploy\*/

配置 GitHub Actions

1. 安装部署插件

安装 hexo-deployer-git 插件，用于将生成的静态文件部署到 GitHub：

1
npm install hexo-deployer-git --save

2. 创建 GitHub Actions 工作流

在项目根目录下创建 .github/workflows 目录，并添加 deploy.yml 文件：

1
2
3
mkdir -p .github/workflows

nano .github/workflows/deploy.yml

3. 配置工作流文件

将以下内容复制到 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
41
42
43
44
45
46
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  # 监听 main 分支的 push 事件

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout source
      uses: actions/checkout@v4
      with:
        submodules: recursive  # 递归获取子模块
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'  # 使用 Node.js 20.x 版本
    
    - name: Cache dependencies
      uses: actions/cache@v4
      with:
        path: ~/.npm
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-node-
    
    - name: Install dependencies
      run: npm install
    
    - name: Generate static files
      run: npx hexo generate
    
    - name: Create .nojekyll file
      run: echo "" > public/.nojekyll
    
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v4
      with:
        personal_token: ${{ secrets.PERSONAL_TOKEN }}
        external_repository: your-username/your-username.github.io
        publish_branch: main
        publish_dir: ./public

设置自动部署

1. 创建 Personal Access Token

为了让 GitHub Actions 能够访问您的仓库，需要创建一个 Personal Access Token：

  1. 登录 GitHub，点击右上角头像 → Settings
  2. 选择 Developer settings → Personal access tokens
  3. 点击 Generate new token
  4. 设置权限：勾选 repo、workflow 等必要权限
  5. 生成并复制 token（只显示一次）

2. 添加 GitHub Secret

在源码仓库中添加 secret：

  1. 进入仓库页面 → Settings → Secrets and variables → Actions
  2. 点击 New repository secret
  3. Name: PERSONAL_TOKEN
  4. Value: 粘贴刚才生成的 token

3. 配置 Hexo 部署设置

编辑 _config.yml 文件，添加部署配置：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/your-username/your-username.github.io.git
  branch: main

首次部署测试

1. 提交代码到 GitHub

执行以下命令将代码提交到 GitHub：

1
2
3
4
5
6
7
8
9
10
11
\# 添加所有文件

git add .

\# 提交更改

git commit -m "Initial commit"

\# 推送到 GitHub

git push -u origin main

2. 查看部署状态

进入 GitHub 仓库的 Actions 页面，查看工作流的执行状态。如果一切正常，部署将自动完成。

GitHub Actions 部署状态

3. 访问博客网站

部署完成后，访问 https://your-username.github.io 即可看到您的博客网站。

最终效果展示

常见问题解决

1. 部署失败的常见原因

  • Node.js 版本不匹配：确保工作流中使用的 Node.js 版本与本地一致
  • 权限问题：检查 Personal Access Token 的权限是否足够
  • 路径错误：确认 publish_dir 路径是否正确
  • 网络问题：GitHub Actions 可能会遇到网络问题，可尝试重新运行工作流

2. 解决方法

1
2
3
4
5
6
7
\# 查看部署日志

\# 进入 GitHub 仓库 → Actions → 选择失败的工作流 → 查看详细日志

\# 本地测试

hexo clean && hexo generate && hexo deploy

3. 自定义域名配置

如果您想使用自定义域名，需要：

  1. 在 source 目录下创建 CNAME 文件，内容为您的域名
  2. 在域名提供商处配置 DNS 解析

优化与扩展

1. 缓存优化

为了加快部署速度，可以配置 npm 缓存：

1
2
3
4
5
6
7
- name: Cache npm dependencies
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

2. 多环境部署

可以配置不同的分支对应不同的环境：

1
2
3
4
5
on:
  push:
    branches:
      - main  # 生产环境
      - develop  # 开发环境

3. 部署到多个平台

除了 GitHub Pages，还可以同时部署到其他平台：

1
2
3
4
5
6
7
deploy:
  - type: git
    repo: https://github.com/your-username/your-username.github.io.git
    branch: main
  - type: git
    repo: https://gitee.com/your-username/your-username.git
    branch: gh-pages

4. 自动化测试

在部署前添加自动化测试：

1
2
- name: Run tests
  run: npm test

总结

通过本文的介绍，您已经学会了如何使用 GitHub Actions 自动部署 Hexo 博客。这种方式不仅提高了开发效率，还能让您专注于内容创作，而不必担心部署的繁琐流程。

部署流程回顾

  1. 本地开发：在本地编写 Markdown 文章
  2. 提交代码：将代码推送到 GitHub 源码仓库
  3. 自动构建：GitHub Actions 自动检测到 push 事件，执行构建流程
  4. 自动部署：生成的静态文件自动部署到 GitHub Pages 仓库
  5. 访问网站：通过 https://your-username.github.io 访问博客

后续建议

  • 主题定制：尝试不同的 Hexo 主题，打造个性化博客
  • 插件扩展：安装更多 Hexo 插件，增强博客功能
  • 监控优化：添加网站监控，及时发现问题
  • SEO 优化：配置 SEO 相关设置，提高网站曝光率

GitHub Pages 设置

希望本文对您有所帮助！如果您在部署过程中遇到任何问题，欢迎在评论区留言讨论。