发表Blog20 分钟读完 (大约3021个字)0次访问

在Github Pages上搭建Hexo博客

名词解释

  • CI/CD: 持续集成 (CI) 和持续部署 (CD)

实现的效果

搭建Hexo博客，源文件推送到开发仓库(可以是私有仓库)，生成的静态文件则推送到GitHub Pages，访问username.github.io即可看到效果。

准备工作

  1. 了解Markdown、Git、GitHub Pages、SSH Key的含义和基本作用
  2. 听说过Hexo博客框架
  3. 已在本地安装好Node、Git、VS Code

环境参考

本地安装并启动Hexo

执行命令

执行命令，然后打开浏览器，输入http://localhost:4000查看效果

1
2
3
4
5
npm install hexo-cli -g
hexo init blog
cd blog
npm install
hexo server

配置参考及目录结构

有能力的建议参考英文文档，中文文档更新不及时，有些教程已经过时或有误。

1
2
3
4
5
6
7
8
9
10
11
|── node_modules    // 外部依赖
|── scaffolds       // 模版文件夹，当您新建文章时，hexo会根据 scaffold来建立文件。
|── source          // 资源文件夹，用于放置文章、图片等资源
|   |── _drafts     // 草稿
|   |── _posts      // 已发布文章
|── themes          // 主题文件夹
|   |── landscape   // hexo官方默认主题
|── .gitignore      // 指定不纳入git版本控制的文件
|── _config.yml     // 配置信息，您可以在此配置大部分的参数。
|── package.json    // 应用程序的信息
|── package-lock.json
  • .gitignore 文件配置参考，用于配置Git忽略版本管理的文件或文件夹：
1
2
3
4
5
6
7
.DS_Store      # 用于控制一个文件夹的显示方式（列表、图标、分栏和CoverFlow）和背景图标等
Thumbs.db      # Windows自动生成的垃圾文件
db.json        # hexo缓存文件
*.log          # 日志
node_modules/  # 外部依赖
public/        # 博客生成的静态文件
.deploy*/      # 执行hexo deploy命令部署到Git上的内容目录

推送源代码并部署到GitHub Pages

建议采用第一种方案，搞定了后发布文章会变得极为简单，可以专注于文章的编写。

以下两种方案均支持源代码推送到私有仓库中，生成的静态文章则推送到username.github.io仓库中。

GItHub Actions - CI/CD

GitHub Actions持续集成服务方案 - 推荐使用此方案

在 GitHub Actions 的仓库中自动化、自定义和执行软件开发工作流程。 您可以发现、创建和共享操作以执行您喜欢的任何作业（包括 CI/CD），并将操作合并到完全自定义的工作流程中。

因此只需要往源文件仓库push更新源文件，GitHub Actions 监控到 push 操作时，就自动拉取源代码并执行 hexo clean、hexo g -d 指令，完成博文发布。

GitHub Actions官方文档: https://docs.github.com/cn/actions/quickstart

注意，项目默认的Action文件是 .github/workflows/分支名称.yml ，如：.github/workflows/main.yml，如果项目中包含该文件，则会在push代码后自动执行workflows。

这里我们直接使用sma11black开发好的GitHub Actions脚本，请先看此教程。

新建源代码仓库和GitHub Pages仓库

  • 在GitHub上新建源代码仓库((可以是私有仓库，GitHub允许用户免费持有一个私有仓库)

  • GitHub Pages仓库名称必须为：username.github.io，如：hormones.github.io

生成SSH Key

在cmd下输入ssh-keygen -t rsa -f ~/.ssh/id_rsa_x -C "你的邮箱"生成公钥和私钥，生成的公钥与私钥位于当前用户家目录的.ssh文件夹中（可在cmd下输入echo %USERPROFILE%查看当前系统用户目录），私钥文件名为id_rsa，公钥文件名为id_rsa.pub

将生成的私钥作为私有仓库下Settings > Secrets 下的一个名叫 DEPLOY_KEY 的 Secret。注意：需要复制私钥中的整个内容。Secret 相当于一个变量，可以使私有变量不公开。

将生成的公钥作为公有仓库下 Settings > Deploy Keys 的 Deploy Key。Deploy Keys 中的公钥针对于当前仓库。

为什么要用 SSH Key？

  • SSH Key，是一对密匙：公钥+私钥，用于加密本地仓库和远程仓库的传输内容。是非对称加密，可公钥加密、私钥解密；或私钥加密、公钥解密。
  • 使用 GitHub Actions 是借助 GitHub 提供的环境，跟本地环境一样，也需要有私钥。当 GitHub Action 执行 hexo g -d 时，用私钥 DEPLOY_KEY 加密，GitHub 用网站文件仓库的 Deploy Key 进行验证。

新建GitHub Actions配置文件

如果源代码分支名为main，则新建配置文件.github\workflows\main.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
44
45
46
# 用于Guthub Actions持续集成
name: Deploy

on: [push]

# 如无特别需求，理论上只需要需改此处的环境变量
env:
  GIT_USER: yourname # 修改为你的用户名
  GIT_EMAIL: xxx@xxx.com # 修改为你的邮箱

jobs:
  build:
    runs-on: ubuntu-latest
    name: A job to deploy blog.
    steps:
    - name: Checkout
      uses: actions/checkout@v2
      with:
        submodules: true # Checkout private submodules(themes or something else).

    # 缓存依赖项以加快workflows（GitHub将删除任何超过7天未访问的缓存条目）
    - name: Cache node modules
      uses: actions/cache@v2
      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
    
    # 部署 hexo 博客网站
    - name: Deploy
      id: deploy
      uses: sma11black/hexo-action@v1.0.4
      with:
        deploy_key: ${{ secrets.DEPLOY_KEY }} # 这就是私钥变量
        user_name: ${{ env.GIT_USER }}  # (or delete this input setting to use bot account)
        user_email: ${{ env.GIT_EMAIL }}  # (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 }}"

Hexo设置

  1. 安装 hexo-deployer-git: npm install hexo-deployer-git --save
  2. 修改配置文件.config.yml
1
2
3
4
5
6
deploy:
  type: git
  # 由于我们使用SSH KEY获取代码权限，则必须要注意路径为ssh格式，如下例所示
  repo: <repository url> # 例：git@github.com:用户名/仓库名称.git
  branch: [branch] # 分支名称
  # message: [message] # 提交到github pages的注释，建议注释掉

提交代码

提交代码后，将会触发Gtihub Actions，此时可以去GitHub上查看效果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 先初始化用户名和邮箱
git config --global user.name "xxx"
git config --global user.email "xxx@yyy.com"

# 初始化本地仓库
git init
# 将文件全部添加到待提交
git add .
# 执行提交，提交到本地仓库
git commit -m 输入本次提交的注释
# 关联github仓库
git remote add origin 这里替换成你的仓库地址
# github新建的仓库主版本已更改为main，原来是master...
# 如果之前使用过github，则不会要求登录，如要求登录，按指引操作即可
git push -u origin main

访问usernme.github.io查看效果

手动构建并推送

这种方案很原始很low，建议使用持续集成服务方案（其实持续集成服务就是程序自动帮你做了一些指令操作而已，时间多的可以先尝试一次手动构建，可以加深对持续集成服务的理解，然后再替换成CI/CD）

上传源代码到仓库

  1. 在GitHub上新建源代码仓库((可以是私有仓库，GitHub允许用户免费持有一个私有仓库)

  2. cmd到工作目录下，输入以下命令后，刷新GitHub，即可看到上传的文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 先初始化用户名和邮箱
git config --global user.name "xxxxx"
git config --global user.email "xxx@yyy.com"

# 初始化本地仓库
git init
# 将文件全部添加到待提交
git add .
# 执行提交，提交到本地仓库
git commit -m "输入本次提交的注释"
# 关联github仓库
git remote add origin 这里替换成你的仓库地址
# github新建的仓库主版本已更改为main，原来是master...
# 如果之前使用过github，则不会要求登录，如要求登录，按指引操作即可
git push -u origin main

手动构建静态文件并上传到GitHub Pages

  1. 在GitHub上新建公有仓库

    注意：公有仓库名称必须为：username.github.io,如：hormones.github.io

  2. 安装hexo-deployer-git

    npm install --save hexo-deployer-git

  3. 在_config.yml配置如下：

    1
    2
    3
    4
    5
    6
    deploy:
      type: git
      # example, https://github.com/hexojs/hexojs.github.io
      repo: https://github.com/<username>/<project>
      branch: [branch] # 分支名称
      message: [message] # 提交到GitHub Pages的注释，可选配置，可以注释掉

  4. 运行hexo clean && hexo deploy。

  5. 访问username.github.io查看效果

拉取源代码到新的工作目录

有时候需要在另外一台电脑上写博客并发布，因此需要拉取仓库中代码下来。

1
2
3
4
5
6
7
8
# cmd到工作空间下，执行以下命令(无需提前创建项目目录，会自动生成)
git clone 这里替换成你的仓库地址
# 安装hexo
npm install hexo-cli -g
# 安装项目依赖：下载完成后，cmd进入项目空间，执行以下命令
npm install
# 查看效果
hexo server

SEO优化

生成 sitemap 站点地图

站点地图是一种文件，您可以通过该文件列出您网站上的网页，从而将您网站内容的组织架构告知 Google 等搜索引擎。搜索引擎网页抓取工具会读取此文件，以便更加智能地抓取您的网站。

先安装谷歌的插件：npm install hexo-generator-sitemap --save

在博客根目录的_config.yml中改url为你的站点地址并添加代码：

1
2
3
4
5
6
7
# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: https://username.github.io/

# add sitemap
sitemap:
  path: sitemap.xml

发布到博客后可以通过https://username.github.io/sitemap.xml查看该文件。

添加 robots.txt

robots.txt是搜索引擎蜘蛛协议，告诉引擎哪些要收录，哪些禁止收录。

source文件夹下新建robots.txt，内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
User-agent: *
Allow: /
Allow: /categories/
Allow: /tags/
Allow: /archives/
Disallow: /js/
Disallow: /css/
Disallow: /fonts/
Disallow: /vendors/
Disallow: /fancybox/

Sitemap: https://username.github.io/sitemap.xml

大家知道Hexo默认的链接是http://xxx.yyy.com/2018/07/14/hello-world这种类型的，这源于站点目录下的配置_config.yml里的配置:permalink: :year/:month/:day/:title/，这种默认配置的缺点就是一般文件名是中文，导致url链接里有中文出现，这会造成很多问题，如使用gitment，也不利于 SEO，另外年月日都会有分隔符。

hexo-abbrlink这个插件，只要不修改md文件的abbrlink的值， url就永久不会改变。如此md文件名和文件内容也可以随便改了。后面的层级更短，这样也有利于SEO优化。

安装：npm install hexo-abbrlink --save

_config.yml配置：

1
2
3
4
permalink: post/:abbrlink.html
abbrlink:
 alg: crc32  # 算法：crc16(default) and crc32
 rep: hex    # 进制：dec(default) and hex

参考链接

在Github Pages上搭建Hexo博客

https://hormones.github.io/post/be2d3818/

作者

Ethan Davis

发布于

2021-09-19

更新于

2021-09-19

许可协议

#

评论

×