Hexo + Github Pages + Github Actions 博客搭建

前言

这已经是我兜兜转转第三次使用Hexo + Github Pages的博客方案了。

阮一峰老师的一段话，我深以为然，这里引用一下：

喜欢写Blog的人，会经历三个阶段。

• 第一阶段，刚接触Blog，觉得很新鲜，试着选择一个免费空间来写。
• 第二阶段，发现免费空间限制太多，就自己购买域名和空间，搭建独立博客。
• 第三阶段，觉得独立博客的管理太麻烦，最好在保留控制权的前提下，让别人来管，自己只负责写文章。

大多数Blog作者，都停留在第一和第二阶段，因为第三阶段不太容易到达：你很难找到俯首听命、愿意为你管理服务器的人。

原文地址：搭建一个免费的，无限流量的Blog----github Pages和Jekyll入门

第一次博客是使用Jekyll搭建的。转到Hexo来还要感谢@Wanghui-Huang这位学长。

后面听说Hugo很快，又转到Hugo去了。到头来，兜兜转转，什么也没学到，也没有留下什么我来过的痕迹。

前几天逛Github的时候，注意到有一个Github Action的新功能。正好我学习过CI/CD，于是再借着搭建博客，顺便体验一下这个新功能。

Hexo

Hexo 中文官方文档：文档 | Hexo

安装

以下内容摘自官网：

前提（依赖）

• node.js（我推荐使用nvm进行环境管理）
• git
  这部分跳过，网上文章很多。

安装 Hexo

很简单，npm一行命令即可安装：

npm install -g hexo-cli

安装完成后，hexo -v验证是否安装成功。
有如下输出即可：

(base)  ~ hexo -v       
hexo-cli: 4.3.0
os: darwin 22.1.0 13.0.1

node: 16.15.1
v8: 9.4.146.24-node.21

使用（建站）

这部分也可以阅读官网教程：建站教程

从使用到访问博客只需要以下四步。

hexo init blog_dir_name
cd blog_dir_name
npm install
hexo server

init和install会下载一些包，可能会耗费一些时间。如果时间过长，可以考虑换源。

默认主题是Landscape，可能很多同学会觉得比较平淡。

基本指令

这部分指令很常用，先记下来。

• hexo clean：清除缓存
• hexo g(or generate)：生成网页资源，每次变更都要做
• hexo s(or server)：本地服务器预览
• hexo d(or deploy)：部署到服务器

换主题

我使用Hexo来体验的原因就是因为我喜欢的主题只有Hexo才有，Jekyll没有，Hugo的还在开发。
我比较推荐以下主题：

• 我的最爱：probberechts/hexo-theme-cactus
• 也很不错，最多人使用：iissnan/hexo-theme-next
• 黄玄大佬的博客模板：Huxpro/huxpro.github.io
  大部分主题的 README都会有写怎么把主题切换过去以及自定义配置。
  以cactus为例，Github主页不仅有Demo，还有详尽的教程。大致如下：

下载主题

有以下两种方式，直接下载源码放置到仓库或者作为git submodule。
!!! 为了后面直接使用 Hexo 官方的 Github Action模板，这里使用第一种方式。如果不打算使用GitHub Action的服务，两种都可以。

git submodule add https://github.com/theme-next/hexo-theme-next themes/next

# or

$ git clone https://github.com/probberechts/hexo-theme-cactus.git themes/cactus

自定义配置

更改根目录下的_config.yml文件。
这部分需要学习一下，比如我新增了如下配置：

title: 我的小站
subtitle: ''
description: ''
keywords: Blog
author: Lucas
language: zh-CN
timezone: 'Asia/Shanghai'

# theme
theme: cactus
theme_config:
  colorscheme: classic
  posts_overview:
    show_all_posts: false
    post_count: 6
  social_links:
    github: http://github.com/your_nickname
    mail: mailto:your_email
  copyright:
    start_year: 2020
    end_year: 2023
  nav:
    home: /
    tag: /tags/
    category: /categories/
    about: /about/
    search: /search/
  highlight: vs
  toc:
    enable: true
    # Automatically add list number to toc.
    number: true
    # If true, all words will placed on next lines if header width longer then sidebar width.
    wrap: false
    # If true, all level of TOC in a post will be displayed, rather than the activated part of it.
    expand_all: false
    # Maximum heading depth of generated toc.
    max_depth: 6

更多自定义配置查看所选主题的文档。

增加导航栏

注意这里的导航栏，我自己新增了几栏，对应需要进行如下操作：

hexo new page about

然后进入source/about/index.html文件，元信息更改如下：

---
title: about
type: about
---

搜索插件

搜索功能需要安装插件。

npm install hexo-generator-searchdb --save

然后按照上面的新增导航栏的操作，新增名为search的page。

写文章发布

hexo new post "hello world"

就会在source/_posts/目录下新建名为hello-world.md的文章。
往里面写内容即可。

如果需要使用标签或者分类，首先按照上面的新增导航栏的操作，新增对应page,名为categories和tags，然后修改type。

使用标签和分类

看示例即可理解。

---
title: Hello World
date: 2021-1-1 23:59:59
tags:
  - Hexo
categories:
  - 'hello world'
---

部署

部署首先需要安装插件，安装命令如下：

npm install hexo-deployer-git --save

部署需要在_config.yml里添加以下内容：

deploy:
  type: git
  repo: > #https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
  branch: [branch]
  message: [message]

我的：

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: 'git'
  repo: [email protected]:xxx/xxx.github.io.git
  branch: master

!!! Github Pages 是需要去Github开启的，这部分网上资料也很多了，不再赘述。

Github Actions 持续集成

以下这部分是进阶内容。只做到上面的程度已经可以发布到Github Pages并享受拥有自己博客的乐趣。
但是Hexo有个地方让我很不爽，每次推到github.io的都只能是生成的网页资源文件，而不可以把源代码也推上去，需要额外操作。
现在有了Github Actions的支持，我们就能建立两个代码仓库，比如：

• blog_src：私有，保存源代码，内有个人数据
• blog.github.io：公开，大家访问的资源
  然后借助Github Actions关联起来，配置完成后不需要额外操作即可实现以上目的。

什么是GitHub Actions

根据官网的介绍：

Automate your workflow from idea to production
GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. Build, test, and deploy your code right from GitHub. Make code reviews, branch management, and issue triaging work the way you want.

想了解更多，这里是官网地址：Github Actions

有的同学可能会问，CI/CD已经有了Jenkins等非常强大的工具，为什么需要使用Github Actions。最大的优势我总结为两点：

• Github 原生支持
• GitHub Actions Marketplace
  我从网上找到一个对比表格（来源：Github Actions or Jenkins? Making the Right Choice for You）：

Jenkins	GitHub Actions
Server needs installation	No installation required as it is on the cloud
Tasks or jobs will be synchronous, which will consume more time to deploy a product to market	Asynchronous CI/CD is achieved
Is based on accounts and triggers and centers on builds which does not conform to GitHub events	Provides actions to every Github event and supports many languages and frameworks
Need to run on a Docker image for environment compatibilit	Compatible with any environment
Plugins are available to support caching mechanisms	Have to write your own caching mechanism if you require caching
Does not have the capability to be shared	Can be shared via the GitHub Marketplace

总而言之，对于个人来说，使用Github Actions非常合适。

语法

参考阮一峰老师的GitHub Actions 入门教程。
核心就四个东西：

1. workflow （工作流程）：持续集成一次运行的过程，就是一个 workflow。
2. job （任务）：一个 workflow 由一个或多个 jobs 构成，含义是一次持续集成的运行，可以完成多个任务。
3. step（步骤）：每个 job 由多个 step 构成，一步步完成。
4. action （动作）：每个 step 可以依次执行一个或多个命令（action）。

其实用不到啥，Hexo有已经写好的配置文件可以直接用。

Hexo + Github Actions

叨叨了这么久，进入正题。
基本遵循GitHub Action - Hexo CI/CD进行配置。

设置Deploy keys 和 Secrets

终端输入下面命令，生成密钥和公钥。

ssh-keygen -t rsa -C "[email protected]"

在哪个目录输入，就在哪个目录下生成。

然后在Github Pages对应的repo，点击repo的设置，点击deploy key，add deploy key 把公钥（也就是带有.pub后缀的文件内容）添加进去，命名为DEPLOY_KEY。注意应该是要给写的权限（Allow write access）。

然后在放置源代码的repo，点击Settings > Secrets > actions > 新建名为 DEPLOY_KEY的secrets，把密钥（不带.pub）的内容粘贴进去。

workflow

在hexo项目的根目录下新建.github/workflows\目录，写入如下内容（来源于上面给的Github Action - Hexo CI/CD链接）中的example文件。

name: Deploy

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    name: A job to deploy blog.
    steps:
    - name: Checkout
      uses: actions/checkout@v1
      with:
        submodules: true # Checkout private submodules(themes or something else).
    
    # Caching dependencies to speed up workflows. (GitHub will remove any cache entries that have not been accessed in over 7 days.)
    - name: Cache node modules
      uses: actions/cache@v1
      id: cache
      with:
        path: node_modules
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-node-
    - name: Install Dependencies
      if: steps.cache.outputs.cache-hit != 'true'
      run: npm ci
    
    # Deploy hexo blog website.
    - name: Deploy
      id: deploy
      uses: sma11black/hexo-[email protected]
      with:
        deploy_key: ${{ secrets.DEPLOY_KEY }}
        user_name: your github username  # (or delete this input setting to use bot account)
        user_email: your github useremail  # (or delete this input setting to use bot account)
        commit_msg: ${{ github.event.head_commit.message }}  # (or delete this input setting to use hexo default settings)
    # Use the output from the `deploy` step(use for test action)
    - name: Get the output
      run: |
        echo "${{ steps.deploy.outputs.notify }}"

可以不更改。要更改的话也很简单，自己看文档。

测试

新建变更，同步到远程分支，就会开始自动打包。
点击源代码repo的action栏，即可查看状态是成功还是正在进行还是失败。

The End