hexo建站及使用Butterfly主题的Quick Start

  1. 安装Node.js (含npm)，Win系统请从官网 下载，输入以下两条命令确认node与npm是否成果安装
1
2
node -v
npm -v
  1. 全局安装Hexo框架
1
2
npm install -g hexo-cli
# 中国大陆镜像 npm install -g hexo-cli --registry=https://registry.npmmirror.com
  1. 初始化Hexo
1
2
3
4
mkdir <username>.github.io
cd <username>.github.io
hexo init .
npm install
  1. 配置Butterfly主题
1
git clone --depth=1 https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

修改根目录底下的_config.yml 里的主题属性值theme: butterfly

  1. 本地预览，默认在http://localhost:4000 上运行
1
2
3
hexo clean
hexo generate 
hexo server

本地预览时遇到pug相关报错

extends includes/layout.pug block content include ./includes/mixins/post-ui

这是由于没有安装相关的包，在根目录运行以下指令

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

自动化部署的两种方式

A. Hexo 源代码和生成的静态文件在不同两个仓库，Github Actions里无需设置，配置.github/workflows/deploy.yml 即会自动尝试部署，不过本人屡次尝试仍然失败

B. 源代码和 Pages 站点托管在同一个仓库，可参考官方文档，配置.github/workflows/pages.yml，并且修改Settings > Pages > Source > Github Actions

Hexo部署时按照默认的Jekyll的工作流运行

Error: Logging at level: debug Configuration file: /github/workspace/./_config.yml Theme: butterfly github-pages 228 | Error: The butterfly theme could not be found

先在根目录下添加名为.nojekyll 的零字节空文件，再在_config.yml 里的include属性下添加

1
2
include:          # <-- put it here (2 spaces indent)
  - .nojekyll

添加主题自动更新的workflow

在.github/workflows/pages.yml的配置文件中添加自动更新的工作流（可能会造成部署时间的延长）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          submodules: recursive
---------------------------------
      - name: Update Butterfly theme
        run: |
          # 删除本地老主题
          rm -rf themes/butterfly
          # 克隆最新版
          git clone --depth=1 https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
----------------------------------
      - name: Use Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: "20"

此处由于自动更新主题每次都会重新拉源码，所以对于主题的定制不能继续在themes/butterfly/_config.yml里了，不然每次更新主题的时候都会把自定义的配置覆盖掉。一般来说Hexo 会先加载你项目根目录下的 _config.yml，然后再加载根目录下的 _config.butterfly.yml 并覆盖默认值，因此需要在根目录下创建属性与themes/butterfly/_config.yml 完全一致的_config.butterfly.yml 并在这里进行修改。