github+Actions搭建静态博客

前言

之前了解了下travis-ci部署博客,虽然方便,但是毕竟设置麻烦,需借用第三方网站功能,前些天看到github也有自动化功能了,百度一番,结果倒是挺多,但是基本没有无错或是某些地方详细说明的,踩了无数的坑,尝试了无数次的操作,总结了此文,有些操作或设置会尽量做到无错,使有需要的人能完美使用。

前期准备

整体规划思路:

  • 本地生成hexo静态博客
  • 配置Actions Workflow 脚本
  • 写博文,push到博客源码仓库,Actions会自动部署博客

目标

因为我自己使用了Coding Pages和Github Pages两个,所以最终也会通过Workflow脚本部署到这两个仓库。这中间有一些东西要讲清楚。比如,博客部署到用户目录,还是项目目录,Coding Pages和Github Pages有什么区别,有什么改动,博客配置文件如何设置。

Github Pages

所有希望部署Github pages的仓库必须是 公开 仓库,或是升级为GitHub Pro,官方原话为:Upgrade to GitHub Pro or make this repository public to enable Wikis.

Pages 类型 Pages 默认分配的 URL 允许的部署来源
Github用户 Pages {username}.github.io master 分支、github-pages 分支、或 master 分支中的 /docs 目录
Github项目 Pages {user_name}.github.io/{project_name} master 分支、或 master 分支中的 /docs 目录
Github项目中的 /docs {user_name}.github.io/{project_name} master 分支、或 master 分支中的 /docs 目录

Coding Pages

2020年以前还分用户和项目pages,在2020年以后,就统一了,URL样式都是统一的 http://XXXX.coding-pages.com,其中XXXX是随机的数字+字母组合。有兴趣的可以查看官方帮助文档。coding官方搭建指南

本文以github用户Pages为前提。如果只是单独部署在github,随意是用户还是顶目都行,记得在hexo设置文件里设置:

第一个坑

_config.ymlroot: /notes-action-pages字段分两种情况:

  • 用户目录pages 设置为 root: /
  • 项目目录pages 设置为 root: /{project_name}

因为coding pages只有一种格式,和github 用户pages的格式相同,不再设置二级项目目录访问,如果在github 项目目录pages生成的静态文件,部署到coding pages时,会目录错误,比如CSS,访问页面找不到,如果有哪个读者知道有更好的解决办法,可以留言告诉我,谢谢。

为了不影响后边设置,请提前准备以下工作。

  • 私有仓库名字随意,比如:blog, 主要存放博客源文源码及日后写作的md文档。
  • 公开仓库:{project_name}.github.io。一个github用户名下,只能有一个仓库能设置为{project_name}.github.io访问地址,也就是gh-pages分支部署的结果。主要存放,public 静态页面的,空的新项目,或是已有的都行。

本地生成hexo博客

具体使用方法,参考官方网站,或自行搜索,本文略过。

设置密钥

为了方便运行 GitHub Actions 时登录 GitHub 账号,我们使用 SSH 方式登录,需设置无密码访问登录。

第二个坑

之前查阅网上资料时,没有人说,用以前现有的公私钥对,还是重新生成新的,公钥是配置在github 网站–>Settings–>SSH and GPG keys还是{project_name}项目–>Settings–>Deploy keys

说明一下,这些设置的区别

  • 以 windows 为例:密钥对文件在 C:\Users\用户名里,其中 Users 可能因为系统原因显示的是用户。这个文件夹里会有一个.ssh 的目录,这个里面就是我们的密钥对。其中 id_rsa 是私钥,id_rsa.pub 是公钥。

  • 配置公钥,也就是 github 网站–>Settings–>SSH and GPG keys的,如果以前就有可以直接用,不用生成新的,然后把 id_rsa.pub 这个文件用文本文档打开,将内容复制进去,如果没有就需要生成新的密钥对,配置方法一样。

  • 配置私钥,把对应的私钥设置在 放置源码如:上文提到的blog仓库的Settings–>Secrets,点击Add a new secret创建一个,Name可以随意,但是下文要用到我设置为:HEXO_DEPLOY_PRIVATE_KEYValue就是与github以前用的公钥对应的私钥或新建对应的私钥内容。

  • 如果没有则需要创建命令为:ssh-keygen -t rsa -C "Github 的邮箱地址" 。使用方法见第二条。

  • 区别: github 网站–>Settings–>SSH and GPG keys,这个是对{username}用户名下所有的仓库都有读写权限。{project_name}项目–>Settings–>Deploy keys,这个只是对本顶目有读写权限,下文部署hexo中用到了在Workflow 脚本clone 另一个不公开的主题仓库,所以本文设置为github 网站–>Settings–>SSH and GPG keys

  • 如果还有不明白的自行找资料,本文不再赘述。

添加 Actions

方法一:

点击私有仓库上方里的 Actions,点击set up a workflow yourself 创建一个新的 actions。自动命名为main.yml,也可以自己命名。
然后在内容框填入以下代码:

脚本中用到的字段,需自己在源码仓库 Settings–>Secrets 添加。

HEXO_DEPLOY_PRIVATE_KEY配置与网站对应的密钥。

GIT_NAME配置名字, GIT_EMAIL配置邮箱。

GH_TOKEN配置。需要自己去 GitHub setting 里申请,方法自行百度。申请后,只显示一次,刷新或重新打开时,不再显示。记得复制保存下。配置时需填入。

CD_TOKEN配置。需要到仓库的项目设置,然后在开发者选项的项目令牌申请。CDT_TOKEN 的内容为 用户名:密码

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
name: Hexo Blog CI  # 自动化的名称

on: # 只在master push 时运行
push: # push的时候触发
branches: # 那些分支需要触发
- master

jobs:
build:
runs-on: ubuntu-latest # 指定运行所需要的运行环境(最新版本) 可选 ubuntu-latest, ubuntu-18.04, ubuntu-16.04, windows-latest, windows-2019, windows-2016, macOS-latest, macOS-10.14
strategy:
matrix:
node-version: [12.x] # 指定node的版本号

steps:
- name: 开始运行 # 使用 actions/checkout 这个插件 用于拉取当前仓库的master分支
uses: actions/checkout@v2 # 脚本来自 https://github.com/actions/checkout

- name: 设置 Node.js ${{ matrix.node-version }} # 使用 actions/setup-node@v1 插件配置node环境
uses: actions/setup-node@v1 # 配置脚本来自 https://github.com/actions/setup-node
with:
node-version: ${{ matrix.node-version }}

- name: 配置 Git 环境
# 该步骤所需的环境变量。
env:
HEXO_DEPLOY_PRIVATE_KEY: ${{ secrets.HEXO_DEPLOY_PRIVATE_KEY }}
run: |
# set up private key for deploy
mkdir -p ~/.ssh/
echo "$HEXO_DEPLOY_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa # 配置秘钥
chmod 600 ~/.ssh/id_rsa
ssh-keyscan github.com >> ~/.ssh/known_hosts
# set git infomation
git config --global user.name "${{secrets.GIT_NAME}}"
git config --global user.email "${{secrets.GIT_EMAIL}}"

- name: 安装 Hexo CI # 安装 hexo-cli 与项目所需的 node_modules
run: |
export TZ='Asia/Shanghai'
npm install hexo-cli -g
npm install
npm audit fix

- name: 安装插件 # npm ls --depth 0 可查看自己安装了哪些插件
run: |
npm install hexo-deployer-git --save
npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-sitemap --save
npm install hexo-generator-category --save
npm install hexo-generator-feed --save
npm install hexo-related-popular-posts --save
npm install pangu --save
npm install quicklink --save
npm install hexo-symbols-count-time --save
npm install hexo-generator-searchdb --save
git clone https://github.com/theme-next/theme-next-pace source/lib/pace
npm install theme-next/hexo-next-tag --save
npm install theme-next/hexo-next-title --save
npm install theme-next/hexo-next-utteranc --save
git clone git@github.com:${{secrets.GIT_NAME}}/你的主题仓库.git themes/主题名字
npm audit fix

- name: 生成静态资源
run: |
hexo clean && hexo g

- name: 部署博客
env:
GH_REF: github.com/${{secrets.GIT_NAME}}/notes-action-pages.git # GitHub 仓库 HTTPS地址 不要用SSH地址,否则出错
GH_TOKEN: ${{ secrets.GH_TOKEN }} # 预先生成 GitHub Token
CD_REF: e.coding.net/${{secrets.GIT_NAME}}/notes-action-pages.git # coding 仓库 HTTPS 地址 不要用SSH地址,否则出错
CD_TOKEN: ${{ secrets.CD_TOKEN }} # 预先生成 coding Token
run: |
# 生成 commit message 默认抓取最后一次提交信息
git log --pretty=format:":lock: Actions CI: %s Site updated: %cd" --date=format:'%Y-%m-%d %H:%M:%S' > commit-message.log
cd ./public
git init
git add .
git commit -F ../commit-message.log
git push -u --force --quiet "https://${GH_TOKEN}@${GH_REF}" master:master
git push -u --force --quiet "https://${CD_TOKEN}@${CD_REF}" master:master
rm ~/.ssh/id_rsa
rm -rf .deploy_git
方法二:

在本地生成hexo博客后,自建.github -> workflows -> xxx.yml复制上边样本代码。

补充

上边Actions脚本中,有几点说明:

  • runs-on: ubuntu-latest 部署环境,虽然可用选项挺多,但是建议用ubuntu,因为私有仓库每月只有2000分钟,超出时间收费,收费如下:
系统 Linux(2 cores, 7GB) Windows(2 cores, 7GB) macOS(2 cores, 7GB)
收费 $0.008/每分钟 $0.016/每分钟 $0.08/每分钟

官方说明文档

  • 主题主题可以用别人的主题,也可以用自己修改或是开发的主题,使用时,可以在插件部分,clone一下就好。

  • {GH_REF} GitHub 仓库 HTTPS地址 不要用SSH地址,否则出错,我试用用SSH的写法,出错。

  • {GH_REF} # coding 仓库 HTTPS 地址 不要用SSH地址,否则出错,同上。

  • git log --pretty=format:":lock: Actions CI: %s Site updated: %cd" --date=format:'%Y-%m-%d %H:%M:%S' > commit-message.log 就是自定义commit 的内容,个性化设置,及时间日期。

安装插件部分,如果是新建的博客,本地没有安装任何插件的,可以使用。如果本地已是完成了所有的插件安装,并已生成了包含所有依赖的 package.jsonpackage-lock.json 那么,只需要保留以下几个即可:

每个项目的根目录下面,一般都有一个package.json文件,定义了这个项目所需要的各种模块,以及项目的配置信息(比如名称、版本、许可证等元数据)。npm install命令根据这个配置文件,自动下载所需的模块,也就是配置项目所需的运行和开发环境。

1
2
3
4
5
- name: 安装插件 # npm ls --depth 0 可查看自己安装了哪些插件
run: |
git clone https://github.com/theme-next/theme-next-pace source/lib/pace
git clone git@github.com:${{secrets.GIT_NAME}}/你的主题仓库.git themes/主题名字
npm audit fix

添加 README

在博客设置页面_config.yml,配置:

1
2
skip_render: #跳过渲染文件或文件夹如: - test.html   - test/*
- README.md

域名

解决方式很简单,在博客根目录的配置文件中找到 skip_render 字段,添加值CNAME,如果是多个值的配置如下:

1
2
3
skip_render: #跳过渲染文件或文件夹如: - test.html   - test/*
- 'README.md'
- 'CNAME'

然后在 /source 的目录中创建一个文件,命名为 CNAME,里边的内容写你的域名。只写域名即可。例如 www.baidu.com,不需要添加 http(s)://


详细使用方法:

关于hexo的_config.yml配置,官方文档中:

  • skip_render:跳过指定文档的渲染,您可使用 glob 表达式来匹配路径。

  • 未说明具体该怎么配置

  • 修改的_config.yml配置文档应为站点文档夹下的,而非主题文档夹下的_config.yml配置文档

  • 可以直接 Ctrl + F 查找 skip_render 关键字

跳过单文档

如果要跳过source文档夹下的test.html,可以这样配置:

1
skip_render: test.html
1
skip_render: [test.html]

跳过多文档

如果要忽略source下的test文档夹下所有文档,可以这样配置:

1
skip_render: test/*

or

1
skip_render: [test/*]

如果要忽略source下的test文档夹下.html文档,可以这样配置:

1
skip_render: test/*.html

or

1
skip_render: [test/*.html]

如果要忽略source下的test文档夹下所有文档和目录,可以这样配置:

1
skip_render: test/**

or

1
skip_render: [test/**]

如果要忽略多个路径的文档或目录,可以这样配置:

1
2
3
4
5
skip_render:
- test.html
- '*.html'
- test/**
- test/*

or

1
skip_render: [test.html, '*.html', test/**, test/*]

参见:如何不处理source目录下某个子目录的所有文档,仅仅是将其copy到public目录中对应目录?
参见:小康博客
参见:eallion