前言

在搭建和维护 Hexo 博客的过程中，我们经常会遇到各种各样的问题。本文记录了我在近期维护博客时遇到的三个主要挑战及其解决方案：

  1. 双仓库自动化部署：源码与页面分离，如何配置 GitHub Actions？
  2. 自定义域名持久化：每次部署后 GitHub Pages 的域名设置都会被重置。
  3. Butterfly 主题定制：如何修复欢迎卡片并将其限制在首页显示。

一、GitHub Actions 双仓库自动化部署

为了方便管理，我采用了源码与部署分离的架构：

  • **源码仓库 (Source)**：Hexo-Blog (私有或公开，存放 Hexo 原始文件)
  • **部署仓库 (Pages)**：kaitumei.github.io (公开，存放生成的静态网页)

1. 遇到的问题

在使用 GitHub Actions 进行自动部署时，默认的 GITHUB_TOKEN 只有当前仓库的权限。当脚本尝试将生成的 public 目录推送到另一个仓库（kaitumei.github.io）时，会报错：

1
2
remote: Permission to kaitumei/kaitumei.github.io.git denied to github-actions[bot].
fatal: unable to access ...: The requested URL returned error: 403

2. 解决方案

我们需要使用 Personal Access Token (PAT) 来替代默认的 Token。

第一步：生成 Token

  1. 前往 GitHub Settings > Developer settings > Personal access tokens。
  2. 生成一个新的 Token (Classic)，勾选 repo 和 workflow 权限。
  3. 复制生成的 Token。

第二步：配置 Secrets

  1. 在源码仓库 (Hexo-Blog) 的 Settings > Secrets and variables > Actions 中。
  2. 新建一个 Repository secret，命名为 GH_PAT，值为刚才复制的 Token。

第三步：优化 Workflow 配置

修改 .github/workflows/autodeploy.yml，使用 peaceiris/actions-gh-pages 插件，并指定 personal_token 和 external_repository。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # ... 省略安装 Node 和 Hexo 的步骤 ...

      - name: 部署
        uses: peaceiris/actions-gh-pages@v4
        with:
          # 关键点 1：使用 PAT 而不是 GITHUB_TOKEN
          personal_token: ${{ secrets.GH_PAT }}
          # 关键点 2：指定生成的静态文件目录
          publish_dir: ./public
          # 关键点 3：指定目标仓库
          external_repository: kaitumei/kaitumei.github.io
          # 关键点 4：指定目标分支 (通常是 main 或 master)
          publish_branch: main
          commit_message: ${{ github.event.head_commit.message }}

二、解决自定义域名频繁重置

1. 现象

每次 GitHub Actions 运行完成后，访问博客域名（如 kaitumei.2345.plus）会失效，GitHub Pages 的设置里 “Custom domain” 变为空白。

2. 原因

Hexo 每次 hexo generate 时会清空并重新生成 public 目录。如果 source 目录下没有 CNAME 文件，生成的 public 目录里也就没有。GitHub 在部署时检测到没有 CNAME 文件，就会重置域名设置。

3. 解决方案

在 source 目录下创建一个名为 CNAME 的文件（无后缀），内容为你的域名：

1
kaitumei.2345.plus

这样，Hexo 生成静态资源时会自动将 CNAME 复制到 public 根目录，GitHub Pages 就能识别并保持域名绑定了。

三、Butterfly 主题欢迎卡片优化

1. 修复 “Network Error”

如果欢迎卡片显示 “Network Error”，通常是因为获取 IP 的 API 请求失败，或者 JS 脚本未正确加载。
确保 _config.butterfly.yml 中注入了脚本：

1
2
3
inject:
  bottom:
    - <script async src="/js/card-welcome.js"></script>

2. 仅在首页显示

默认情况下，Widget 组件可能会在所有页面显示。如果我们希望欢迎卡片只在首页出现，可以通过修改 Pug 模板实现。

修改文件：themes/butterfly/layout/includes/widget/index.pug

修改前：

1
!=partial('includes/widget/card_welcome', {}, {cache: true})

修改后：

1
2
if is_home()
  !=partial('includes/widget/card_welcome', {}, {cache: true})

将判断逻辑放在父容器中，可以避免组件内部逻辑导致的布局错乱问题。

总结

折腾博客的过程就是不断踩坑和填坑的过程。通过配置 GitHub Actions 和 PAT，我们实现了优雅的跨仓库自动化部署；通过简单的 CNAME 文件，解决了域名重置的烦恼；通过对 Pug 模板的微调，让主题展现更加符合心意。

希望这篇记录能帮助到遇到同样问题的你！