0. 背景

由于 2021 年的旧博客源码丢失，仅剩渲染后的 HTML 静态文件，我决定在 M4 Mac mini 上进行博客重建。本次重建的核心目标是实现“源码安全备份”与“一键自动化发布”，确保以后即便更换硬件，也能通过 Git 快速恢复工作流。

1. 架构设计：双仓库策略

为了兼顾私密性和展示需求，我采用了双仓库架构：

  1. blog-source (Private)：存放 Hexo 源码、Markdown 原稿、各种配置文件，不对外开放。
  2. UserName.github.io (Public)：仅存放 hexo g 渲染后的静态 HTML 文件，由 GitHub Pages 托管。

2. 本地环境搭建

环境整备完全遵循“外置存储”原则，所有环境和数据均位于外置 SSD 中。

A. 基础依赖安装

1
2
3
4
5
# 安装 Node.js
brew install node

# 安装 Hexo 命令行工具
npm install -g hexo-cli

B. 初始化与主题安装

1
2
3
4
5
6
7
8
9
# 外置SSD的名称是 Samsung，如果不同请自行替换
cd /Volumes/Samsung/go_workspace
hexo init chianchuan-blog
cd chianchuan-blog
npm install

# 安装 Butterfly 主题及其必要渲染引擎
git clone -b master https://github.com/jerryclyw/hexo-theme-butterfly.git themes/butterfly
npm install hexo-renderer-pug hexo-renderer-stylus --save

3. 自动化流水线 (CI/CD) 配置

这是本次搭建的核心。通过 GitHub Actions，我实现了“只要 git push 源码，云端自动部署”的闭环。不用先把源码推送到 GitHub，再将静态 HTML 推送到 GitHub Pages。

A. 准备工作：生成 PAT 令牌

  1. 在 GitHub Settings 生成一个 Personal Access Token (PAT)，勾选 repo 权限。
  2. 在私有仓库 blog-source 的 Settings -> Secrets 中，添加名为 HEXO_DEPLOY_KEY 的变量，值为刚才的 Token。

B. 编写 Workflow 剧本

在项目根目录创建 .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 Deploy

on:
  push:
    branches:
      - main # 触发分支

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

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

      - name: Install Dependencies
        run: |
          npm install -g hexo-cli
          npm install

      - name: Deploy
        env:
          MY_TOKEN: ${{ secrets.HEXO_DEPLOY_KEY }}
        run: |
          git config --global user.name "Arisa"
          git config --global user.email "你的邮箱"
          
          # 核心逻辑：强行替换 _config.yml 里的 repo 地址，注入 Token 提权
          sed -i "s|repo:.*|repo: https://x-access-token:${MY_TOKEN}@github.com/UserName/UserName.github.io.git|g" _config.yml
          
          hexo clean
          hexo g
          hexo d

4. 过程中踩过的坑与解决方案

A. 主题文件夹上传失败（No Layout Warning）

问题：themes/butterfly 包含 .git 文件夹，导致主 Git 将其识别为子模块而跳过文件上传，导致云端渲染白屏。

解决：

1
2
3
rm -rf themes/butterfly/.git
git add themes/butterfly
git commit -m "fix: remove submodule and add theme files"

B. Git 协议导致推送失败

问题：Error in the HTTP2 framing layer。

解决：

1
git config --global http.version HTTP/1.1

5. 总结：我的日常发布工作流

  1. 写文：GoLand 顶部按钮一键 New Post，本地 hexo s 预览。
  2. 插图：直接粘贴，PicGo 自动处理。
  3. 发布：git add . -> git commit -> git push。（也可以直接在 GoLand 上提交与推送）
  4. 生效：等待 1 分钟，GitHub Actions 自动完成线上更新。

这套系统极大降低了写作的心理负担，让我能把精力完全聚焦在平常学习与项目复盘上。