使用 GitHub Actions 实现 Hexo 博客自动部署到cloudflare

发表于 分类于 ， 阅读次数： 本文字数： 1.8k 阅读时长 ≈ 6 分钟
在本篇文章中，我将分享如何利用 GitHub Actions 实现自动发布 Hexo 博客。这将极大地简化发布博客的流程，让你专注于内容创作，而无需手动部署。以下是具体步骤及可能遇到的问题和解决方案。

前言

作为一名博客写作者，手动部署 Hexo 博客到 GitHub Pages 既繁琐又容易出错。本文将详细介绍如何使用 GitHub Actions 实现 Hexo 博客的自动部署，让你专注于内容创作，让技术自动化为你服务。

什么是 GitHub Actions？

GitHub Actions 是 GitHub 提供的持续集成和持续部署 (CI/CD) 平台，允许你在代码仓库中自动化构建、测试和部署流程。对于 Hexo 博客来说，这意味着：

  • ✅ 自动检测内容更新
  • ✅ 自动构建静态文件
  • ✅ 自动部署到 GitHub Pages
  • ✅ 完全免费的自动化流程

获取 GitHub Token

要让 GitHub Actions 有权限操作你的仓库，你需要创建一个 Personal Access Token。

创建 Token 步骤：

  1. 登录 GitHub，点击右上角头像 → Settings
  2. 左侧菜单栏找到 Developer settings
  3. 选择 Personal access tokens → Tokens (classic)
  4. 点击 Generate new token → Generate new token (classic)
  5. 配置 Token 信息：
    • Note: hexo_auto_deploy（描述用途，token的名称）
    • Expiration: 建议选择 No expiration（永不过期）
    • Select scopes: 勾选以下权限：
      • repo（完全控制仓库）
      • workflow（工作流权限）
  6. 生成 Token：点击 Generate token，立即复制生成的 Token（只会显示一次！）

在仓库中配置 Token：

  1. 进入你的 Hexo 博客仓库
  2. 点击 Settings → Secrets and variables → Actions
  3. 点击 New repository secret
  4. 填写：
    • Name: GH_TOKEN
    • Value: 粘贴刚才复制的 Token
  5. 点击 Add secret

在同仓库中创建备份分支

hexo利用git分支进行博客源码备份

也可以另外新建一个仓库或者是分支都是可以的，然后在仓库中创建** .github/workflows/deploy.yml**这个文件。

创建 GitHub Actions 工作流

在你的 Hexo 博客仓库中创建 .github/workflows/deploy.yml 文件，内容如下：

name: Blog自动部署 # 工作流名称

on:
  push:
    branches: hexoBackup  # 监测 hexoBackup 分支的推送 这个是新创建的分支
    paths: # 只监测特定文件类型的变动
      - '*.json'
      - '**.yml'
      - '**/source/**'

env:
  NODE_VERSION: '22.x'  # 定义 Node.js 版本
  
jobs:
  blog: # 任务名称
    timeout-minutes: 30 # 设置 30 分钟超时
    runs-on: ubuntu-latest # 使用最新 Ubuntu 系统
    
    steps:
      - uses: actions/checkout@v4 # 从hexoBackup分支中拉取代码
      
      - name: 设置node环境 ${{ env.NODE_VERSION }}
        uses: actions/setup-node@v4 # 设置 node.js 环境
        with: 
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'  # 自动缓存 npm 依赖
          
      # 缓存 node_modules，提高编译速度
      # GitHub 服务器编译速度极快，每月 2000 分钟免费额度足够使用
      - name: 缓存 Hexo 构建
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-
            
      # 安装源代码所需插件     
      - name: Init Node.js
        run: |
          sudo timedatectl set-timezone "Asia/Shanghai"  # 设置时区
          npm install --force  # 强制安装依赖
          echo "init node successful"

      - name: Install Hexo-cli
        run: |
          npm install -g hexo-cli --save  # 全局安装 Hexo CLI
          echo "install hexo successful"
          
      - name: 环境检查
        run: |
          node --version    # 检查 Node.js 版本
          npm --version     # 检查 npm 版本
          npx hexo --version  # 检查 Hexo 版本
          echo "✅ 环境检查完成"

      - name: 清理并生成静态文件
        run: |
          hexo clean        # 清理旧文件
          hexo generate --debug  # 生成静态文件，开启调试模式
          echo "✅ 博客构建成功"
          
          # 验证生成结果
          if [ ! -d "public" ]; then
            echo "❌ 错误：public 目录未生成"
            exit 1
          fi
          echo "📁 生成文件数: $(find public -type f | wc -l)"

      - name: 传统方式部署 
        run: |
          git config --global user.name "xxxx"        # 设置 Git 用户名
          git config --global user.email "xxxxx"      # 设置 Git 邮箱
          hexo deploy      # 执行 Hexo 部署
        env:
          GIT_USER: xxxxx
          GIT_EMAIL: xxxxx

      - name: 构建失败通知
        if: failure()      # 只在构建失败时运行
        run: |
          echo "❌ 构建失败！请检查错误日志"
          exit 1

代码详细解析

触发器配置 (on)

on:
  push:
    branches: hexoBackup
    paths:
      - '*.json'
      - '**.yml'
      - '**/source/**'
  • branches: 指定只在 hexoBackup 分支的推送时触发
  • paths: 智能监控，只在以下文件变动时运行：
    • 所有 JSON 配置文件
    • 所有 YAML 配置文件
    • source 目录下的所有内容（你的文章和资源）

环境变量 (env)

env:
  NODE_VERSION: '22.x'

集中管理环境变量，便于维护和修改。

缓存策略

- name: 缓存 Hexo 构建
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}

缓存机制说明：

  • path: 缓存 npm 全局安装目录
  • key: 基于操作系统、缓存名称和 package-lock.json 的哈希生成唯一键
  • restore-keys: 缓存回退策略，如果精确匹配失败，尝试匹配相近的缓存

依赖安装优化

- name: Init Node.js
  run: |
    sudo timedatectl set-timezone "Asia/Shanghai"
    npm install --force
  • 时区设置: 确保日志时间准确
  • --force 参数: 解决可能的依赖冲突问题

部署流程

- name: 传统方式部署 
  run: |
    git config --global user.name "xxxxx"
    git config --global user.email "[email protected]"
    hexo deploy

这里使用 Hexo 原生的 deploy 命令，需要在你的 _config.yml 中配置部署信息：

# Deployment  {token} 为上面生成的 github令牌token
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  - type: git
    repository: 
      #github: [email protected]:xxx/xxxx.github.io.git,main
      #B860ssh: [email protected]:/home/gitHexo/hexoNext.git,master
      github: https://{token}@github.com/xxxx/xxxx.github.io.git,main
    ignore_hidden: false  #
  - type: baidu_url_submitter

第三步：配置 Hexo 部署设置

在你的 Hexo 博客根目录的 _config.yml 文件中添加部署配置：

# Deployment
deploy:
  type: git
  repo: https://[email protected]/你的用户名/你的仓库名.git,gh-pages

重要: 将 github_token 替换为 ${{ secrets.GH_TOKEN }}，GitHub Actions 会自动替换为你在 Secrets 中设置的 Token。

第四步：测试自动部署

  1. 提交代码：将工作流文件推送到 hexoBackup 分支
  2. 查看运行状态：
    • 进入仓库页面
    • 点击 Actions 标签页
    • 查看工作流运行状态
  3. 验证部署：访问你的 GitHub Pages 地址查看是否更新

高级优化建议

设置仓库密钥

我们不应该将Token直接写在代码中，所以可以使用GitHub Secrets来存储Token，然后在工作流中将其转换为_config.yml中的配置，或者使用环境变量。

在这个分支仓库中点击仓库的【Settings】-【secrets and variables】-【New repository secret】-【New secret】

**Name ：**hexo_token（这个随便取）

**Secret ：**上面创建的github的令牌token。

假设我们在Secrets中设置了一个名为hexo_token的秘密变量，我们可以使用sed命令来替换，例如：

# 原来是这样的
deploy:
  - type: git
    repository: 
      github: [email protected]:xxxx/xxxx.github.io.git,main
    ignore_hidden: false  #
  - type: baidu_url_submitter

sed -i "s|[email protected]:|https://${{ secrets.hexo_token}}@github.com|g" _config.yml

将 [email protected]:替换为 https://${{ secrets.hexo_token}}@github.com

然后我们在工作流中添加一个步骤：

- name: 修改_config.yml中的部署仓库URL
    run: |
      sed -i "s|[email protected]:|https://${{ secrets.hexo_token }}@github.com|g" _config.yml

使用更专业的部署 Action

- name: 部署到 GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GH_TOKEN }}
    publish_dir: ./public
    publish_branch: gh-pages

多环境支持

env:
  NODE_VERSION: '22.x'
  TZ: 'Asia/Shanghai'
  
jobs:
  build-and-deploy:
    strategy:
      matrix:
        node-version: [18.x, 20.x, 22.x]

常见问题解决

权限错误

Git提交时报错： 

To https://github.com/quantum6/jdk8u-tsit
 ! [remote rejected]       quantum6 -> quantum6 (refusing to allow a Personal Access Token to create or update workflow `.github/workflows/submit.yml` without `workflow` scope)
error: failed to push some refs to 'https://github.com/quantum6/jdk8u-tsit'
  • 错误原因：

Token没有workflow权限。

  • 解决办法1：修改Token

  • 解决办法2：新建Token

【Hexo自动部署】

使用 GitHub Actions 自动发布 Hexo 博客

Hexo+GitHub搭建个人博客，实现云端编辑、一键发文