目标
1. 个人博客页制作：使用hexo制作静态网页，本地预览无问题后，通过GitHub pages实现线上发布
2. 博客页面更新自动化：将源码托管至GitHub仓库，配置GitHub Actions，实现此后需要更新博文时，仅需一次提交操作即可
前置准备
GitHub
- 创建GitHub账号
- 创建一个Repository（也即仓库）
使用username.github.io命名，用于存放生成的静态页面和生成GitHub Pages。设置为Public。 - 安装GitHub Desktop
桌面软件其实不是必须，但如果不大习惯用命令行，建议安装。仓库的克隆、同步均可通过它实现。
安装开发环境和框架
这里选择的是Hexo框架，开发环境方面需要做以下准备：
- 安装Homebrew
打开terminal，输入以下内容来安装Homebrew。1
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- 安装Git
打开terminal，输入brew install git。
安装完成后，在terminal输入git -v来查看所安装的git版本。 - 安装Node.js
在terminal输入brew install node。
安装完成后，在terminal输入node -v和npm -v来查看所安装的node和npm的版本。 - 安装Hexo
在安装完前面的内容后，在terminal输入npm install -g hexo-cli以安装Hexo。
具体实现
1 个人博客页制作
1.1 创建Hexo项目
通过以下代码，创建Hexo项目：
1 | hexo init path/to/folder/folder_name |
创建完成后，可以得到如下结构的初始化项目文件夹。
1.2 配置网页基本属性
打开项目根目录下的_config.yml文件，设置网页的基本属性。配置项释义见Hexo-Configuration。
1.3 克隆并配置theme
- 找一个喜欢的主题
在Hexo-themes上找一个喜欢的页面主题，点击主题名称即可进入主题的GitHub仓库。 - fork主题的仓库
点击仓库页面上的fork按钮，将该主题克隆到自己的GitHub账号下。 - 将主题克隆到本地
所有的theme代码文件都应当分别以文件夹的形式存放在项目根目录下的themes文件夹中。
打开terminal，进入themes文件夹：将想要使用的主题克隆到themes下（可直接使用开发者提供的installation指引中的指令）:1
cd path/to/the/themes/folder
克隆完成后，可在themes文件夹下看到所有可调用的主题。1
git clone https_link_to_theme_repository theme_name
- 启用主题
打开项目根目录下的_config.yml文件，将themes的内容设置为想要使用的主题。注意这里的名称需要与themes下主题所在的文件夹的名称一致。1
themes: theme_folder
- 调整主题配置
不同的主题，提供不同的可配置项，这些内容可以在主题文件下的_config.yml文件中进行配置。
注意，不同的主题可能不支持自动生成诸如tag、category文件夹，此时可能需要进行手动操作。具体需查看theme仓库中的readme文件。
补充：如果不希望在后续形成GitHub仓库的关联，在这一步引入主题时，也可以选择直接下载主题源码文件并复制到themes文件夹的方式，注意命名时依然要用主题的名称来命名存放源码的文件夹。
1.4 本地预览
配置完成项目文件和项目主题后，可以在本地查看生成效果。
- 使用hexo生成网页：
1
hexo generate
- 生成本地预览：
1
hexo server
- 浏览器输入terminal返回的预览地址，即可在本地查看生成的网页。
1.5 创建一篇博文
需要生成静态网页的博文都应存放在项目根目录下的source文件夹中，其中,_posts文件夹用于存放需要发布到线上文章，_draft文件夹用于存放文章草稿，不会生成网页。
- 打开terminal，进入项目根目录：
1
cd path/to/root/folder
- 创建一个博文文档（不特别声明layout时，新生成的文档会被存放在
_post文件夹中）此时，可以在对应文件夹中找到新生成的.md文档，选择本地支持markdown语法的编辑器打开该文档，在文档的开头，需要对文章的属性做一定声明：1
hexo new [layout] <title>
不同的主题会依据文档的各个属性按照设定的逻辑进行渲染，具体可用属性和渲染效果可查看主题开发者的文档和demo。1
2
3
4
5
6
7
8---
title: title of the post
layout: post
tags:
- tag_1
- tag_2
category: cat_1
--- - 回到浏览器的本地预览页，刷新页面后即可查看基于这篇博文生成的网页内容。
1.6 将网页发布到线上
- 在项目根目录下的
_config.yml文件中，添加如下配置来声明发布的方式、目标仓库、目标分支和备注信息：1
2
3
4
5deploy:
type: git
repo: <blog repository url> # e.g. https://github.com/username/username.github.io
branch: [branch]
message: [message] - terminal保持在项目根目录下，并输入以下内容，将生成的网页推送到目标仓库:
1
hexo deploy
- 打开github.com进入
username.github.io仓库，切换至Settings，在侧边栏中找到Pages，设定静态网页所使用的分支。
当页面显示”your site is live at username.github.io”说明网页已准备就绪，点击后面的Visit Site按钮即可查看。
1.7 后续更新
完成前序步骤后，在线博客页面已经搭建完成，后续推送新博文时，需要：
- 创建博文文档，并以.md的格式保存，注意书写时需要遵循markdown语法（也可使用笔记软件提供的导出md文件来实现）
- 将新的博文复制或移动到项目根目录下的
source/_post文件夹中 - 打开terminal，逐个输入以下命令：
1
2
3
4cd path/to/root/folder
hexo clean && hexo generate
hexo server # 若无需本地预览，可跳过这一步
hexo deploy
2 博客页面更新自动化
本节尝试借助GitHub Actions实现博客页面的自动化生成和发布。
2.1 将代码托管至GitHub仓库
前一节中，上传到username.github.io的文件是编译之后的结果文件，而为了实现网页生成的自动化，首先需要将源码传到线上。
- 将项目根目录添加为git可以管理的仓库
打开terminal，进入项目根目录将当前文件夹添加为git可以管理的仓库（后称1
cd path/to/root/folder
blog_src仓库）1
git init
- 声明不需要上传的项
Finder中打开项目根目录文件夹，Command+Shift+.开启显示隐藏文件，找到.gitignore文件，在其中添加在进行本地和云端代码同步时需要“忽略”的文件或文件夹。在hexo项目中，需要忽略的内容应至少包括public/。
以下是一个样例:1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17# .gitignore for Hexo
# Ignore generated files
*.log
*.log.*
node_modules
public /
# Ignore Hexo files
.DS_Store
Thumbs.db
# Ignore deployment files
.deploy*/
.deploy.sh
# Ignore local configuration file (if any)
_config.local.yml
- 将根目录中的文件添加为待提交的对象（暂存对象）
terminal保持在项目根目录下，输入以下内容：1
git add .
- 提交代码
terminal保持在项目根目录下，输入以下内容：完成以上内容后，GitHub上应当可以查看该项目创建的仓库，仓库中应当包括本地根目录下所有没有被声明需要需要忽略的文件及文件夹。注意该仓库应当始终为Private。1
git commit -m "First commit"
2.2 将引用的主题添加为项目的子模块
在项目中用的主题，是以子模块的方式整个引入的，而项目与子模块之间不会直接关联。因此需要将所引用的主题添加为本项目的子模块，使得后续在自动化编译时，机器能够读取到主题内的配置内容。
- 使用命令行添加子模块
terminal保持在项目根目录下，输入以下内容将引用的主题添加为项目的子模块：1
git submodule add https://github.com/example/submodule.git my-submodule
- 声明子模块的名称及项目地址
Finder中进入项目根目录，打开.gitmodules文件，在文件中声明本项目所引用的子模块。以下是一个样例：1
2
3
4
5
6
7[submodule "themes/submodule1"]
path = themes/submodule1_folder
url = https://github.com/example/submodule1.git
[submodule "themes/submodule2"]
path = themes/submodule2_folder
url = https://github.com/example/submodule2.git
2.3 配置秘钥
为了在打通发布通道的同时保证发布路径的安全，需要引入Deploy Key。Deploy Key是一对SSH密钥，包括公钥和私钥。
- 获取Deploy Key
在terminal中输入以下内容，以生成SSH密钥：以上的指令将得到id_rsa.pub和id_rsa两个文件，前者为公钥，后者为私钥。1
ssh-keygen -t rsa -b 4096 -C "[email protected]"
须注意的是，生成的密钥如果被存放在项目根目录下，可以手动将其移动到合适的位置进行保管，或者在.gitignore中添加新获取的两个文件，以保证其仅保存在本地。 - 将公钥添加到
username.github.io仓库
GitHub中，进入username.github.io仓库，切换至Settings，在侧边栏Security分类下找到Deploy Keys。
点击“add deploy Key”按钮，设置公钥Title，并将公钥文件中的内容完整复制粘贴到Key的输入框中，勾选Write权限，点击“add Key”按钮保存。
- 将私钥添加到
blog_src仓库
GitHub中，进入blog_src仓库，切换至Settings，在侧边栏Security分类下，找到并展开Secrets and Variables，选择Actions。
点击“New repository key”按钮，设置私钥名称，并将私钥文件中的内容完整复制粘贴到Key的输入框中，点击“add Secret”按钮保存。
注意：这里设置的私钥名称将在下一步添加Actions配置时使用，需使用可读性高的方式命名。
2.4 添加Actions配置文件
做好以上的准备后，最后一步就是配置自动化流程。
自动化流程的配置，在GitHub中，通过添加workflow配置文件实现。workflow配置文件的作用是告诉机器在什么条件下需执行当前任务，以及任务中每一步具体要做什么，同时向机器提供必要的鉴权材料。
- 创建workflow配置文件
在项目根目录下找到.github/workflow文件夹（若不存在可手动创建），并在该文件夹下创建deploy.yml文档。
- 在文档中添加生成页面所需执行的内容
打开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
40
41
42
43
44name: Deploy to GitHub Pages
on:
push:
branches:
- main # 每当向当前仓库的main分支推送更新时，触发后面的任务
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout
uses: actions/checkout@v4
with:
submodules: 'true' # 设为true表示读取子模块内容
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: 16 # 替换成实际使用的node版本
- name: Install npm
run: npm install
- name: Install Hexo
run: npm install hexo-cli -g
- name: clean publish_dir
run: hexo clean
- name: Generate Site
run: hexo generate
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
deploy_key: ${{ secrets.DELOPY_KEY }} # DEPLOY_KEY换成私钥的名称
publish_dir: ./public
user_name: 'your_username'
user_email: 'your_email_address'
commit_message: 'Update site'
external_repository: username/username.github.io
publish_branch: 'branch_name' #设置成用于生成GitHub Pages的分支，默认为main - 将本地更新的内容推送至
blog_src仓库
完成workflow配置文件的编辑后，需要将它和项目根目录下其他发生变动的内容一起推送到blog_src仓库。机器会自动识别.github/workflow下的配置文件。
注意：在提交根目录变动前，应先完成提交子模块的变动。 - 编辑博文内容，再次推送更新，查看workflow执行情况
由于定义的workflow在推送更新时触发，因此在完成前一步同步之后，需要再次推送变动，以触发任务，来验证workflow是否能正常工作。
- 编辑博文内容并保存，通过命令行或GitHub Desktop推送更新。
- 进入blog_src仓库，切换至Actions，可以看到workflow列表，点击列表中的名称（也即推送时所留下的comment），进入工作流实例页，可以在该页面查看任务的具体执行情况、debug内容等。若一切运转正常，执行完成后，任务流实例是Success的状态。
- 进入username.github.io仓库，切换至Actions，可以看到有名为pages build and deployment的工作流实例在执行。当该工作流实例状态变更为Success后，就可以前往博客页面进行最终结果验证。
其他拓展
配置自定义域名：Github pages使用自定义域名
结合cloudflare配置CDN加速：免备案加速Blog访问：Cloudflare CDN