HEXO简介

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他标记语言）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。

它可以通过选择、配置 Themes 来定制个性化的博客页面。使用时只需要专注于博客内容的编辑即可，Hexo可以把 Markdown 类型的内容解析成 Html+CSS+JS的静态页面。

具体的安装、配置流程可参阅官方文档。本博客就是基于 Hexo 框架+Butterfly 主题 生成的。

常用命令

  • hexo init

    hexo init 命令用于初始化本地文件夹为网站的根目录

    1
    hexo init [folder]
    • folder 可选参数，用以指定初始化目录的路径，若无指定则默认为当前目录

  • hexo new

    hexo new 命令用于新建文章，一般可以简写为 hexo n

    1
    hexo new [layout] <title>
    • layout 可选参数，用以指定文章类型，若无指定则默认由配置文件中的 default_layout 选项决定
    • title 必填参数，用以指定文章标题，如果参数值中含有空格，则需要使用双引号包围

  • hexo generate

    hexo generate 命令用于生成静态文件，一般可以简写为 hexo g

    1
    hexo generate
    • -d 选项，指定生成后部署，与 hexo d -g 等价

    详细信息请参考：https://hexo.io/docs/generating

  • hexo server

    hexo server 命令用于启动本地服务器，一般可以简写为 hexo s

    1
    hexo server
    • -p 选项，指定服务器端口，默认为 4000
    • -i 选项，指定服务器 IP 地址，默认为 0.0.0.0
    • -s 选项，静态模式 ，仅提供 public 文件夹中的文件并禁用文件监视

  • hexo deploy

    hexo deploy 命令用于部署网站，一般可以简写为 hexo d

    1
    hexo deploy
    • -g 选项，指定生成后部署，与 hexo g -d 等价

  • hexo clean

    hexo clean 命令用于清除 hexo generate 产生的静态网页文件

    1
    hexo clean

部署流程——GitHub Pages

Github Pages简介

Websites for you and your projects.
Hosted directly from your GitHub repository. Just edit, push, and your changes are live.

您和您的项目的网站。
直接从您的GitHub仓库托管。只需编辑、推送，您的更改就会实时生效。

GitHub Pages是GitHub提供的一个免费的静态网站托管服务。它允许用户将自己的 GitHub 仓库转换成一个公开访问的静态网站。这意味着您可以将存储库中的HTML、CSS、JavaScript等静态文件直接部署为一个可通过浏览器访问的网站，而无需搭建服务器或后端代码。

通过将代码提交到GitHub存储库，您的网站会自动构建和更新。您可以选择使用GitHub提供的默认域名，或者绑定自己已拥有的域名来访问网站。

创建 GitHub 仓库

需要 注册 GitHub 账号并 创建 GitHub 仓库来放置网页的静态文件

  • 仓库名的格式必须为<用户名>.github.io 用户名填写自己的
  • 之后部署成功后访问URL即为<用户名>.github.io

配置SSH

本地生成SSH公私钥后，把公钥设置到Github账号中，这里不做过多说明。具体操作可自行查阅。

生成静态网页

在Hexo工程的根目录执行 hexo generate ，Hexo则会解析source文件夹内的Markdown文件，在public文件夹中渲染、生成为静态网页文件

  • 建议生成之前先执行hexo clean 清除上一次生成的文件，避免引起预料外的错误。

部署

在运行hexo deploy 命令一键部署之前，需要先修改Hexo工程根目录下的_config.yml文件，配置部署的参数

1
2
3
4
deploy:
  type: git
  repository: git@github.com:Kagenui-yozuru/Kagenui-yozuru.github.io.git
  branch: main

  • type ：部署类型，这里固定填git

  • repository：仓库地址，换成自己仓库的SSH访问地址

    • SSH访问地址可以在仓库界面 Code 按钮、SSH选项里获取

  • branch：分支名，因为是静态文件，直接推送至主分支即可。GitHub 主分支的名称默认为 main

配置完成后在Hexo工程的根目录执行 hexo deploy 命令即可完成部署。

存在问题

  • 由于网络防火墙的存在，GitHub在国内完全是随缘访问的，在正常的网络环境下访问延迟很高。即使 ”我国开源软件开发者数量突破800万”，这800万名开源软件开发者也不能合法访问Github。所以GitHub Pages只能作为一个低成本、便捷的部署方案，可用性很低。

部署流程——Nginx+Git

方案简介

刚才提到了Hexo 为静态博客。要想将博客部署到私有服务器，只需要把Hexo生成(generate)的静态网页文件上传至服务器。然后通过配置Nginx访问静态文件就可以了。

并且由于Hexo本身支持以Git的方式部署，所以我们可以把Git作为静态网页文件上传至服务器的方案。最终可以实现通过hexo deploy 命令部署。

大致流程为：

  1. 写博客。并将博客文件放到source文件夹下。

  2. 通过hexo g将source文件夹下的.md文件生成静态网页文件，放置于public。

  3. 执行hexo d将public下的文件通过git同步到私有服务器上的远程仓库。

    • 和部署至GitHub Pages 稍有不同的是，这里是将文件同步到自己的私有服务器而非Github

  4. 将服务器上Nginx的静态资源文件夹与仓库绑定

  5. 访问博客的网址，通过Nginx访问服务器上存放的静态文件。

创建用户

1
2
useradd  hexo
passwd hexo

配置Git

安装Git

不同Linux系统安装Git的命令不同，下面以CentOS为例：

1
yum -y install git

创建Git仓库

我把仓库放在了git用户的工作目录/home/hexo/repo/blog.git。注意这个文件夹并不是存放网页静态文件的地方。

1
2
3
4
su hexo
mkdir -p /home/hexo/repo
cd /home/hexo/repo
git init --bare blog.git
  • 注意，要以hexo用户执行以上命令

创建Nginx静态资源文件夹

1
mkdir -p /root/docker/nginx/html/yozuru.cn

我将文件放在了/root/docekr/nginx/html/yozuru.cn。在创建在root目录下不是好习惯，不要学。

配置Git Hooks

进入git仓库的hooks目录，创建post-receive文件

1
2
cd /home/hexo/repo/blog.git/hooks
vim post-receive
  • 注意，要以hexo用户执行以上命令

将如下内容复制进去，并保存

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
#!/bin/bash
read oldrev newrev refname
branch=$(echo $refname | cut -d'/' -f3)

echo "---- Git Post-Receive Hook ----"
echo "Ref: $refname ($branch)"

if [ "$branch" = "main" ]; then
  echo "Deploying main branch..."
  sudo /usr/bin/git --work-tree=/root/docker/nginx/html/yozuru.cn --git-dir=/home/hexo/repo/blog.git checkout -f

  if [ $? -eq 0 ]; then
    echo "Git checkout successful. Reloading Nginx..."
    sudo /usr/bin/docker exec nginx nginx -s reload
    if [ $? -eq 0 ]; then
      echo "Nginx reloaded successfully."
    else
      echo "Error reloading Nginx." >&2
    fi
  else
    echo "Error during git checkout." >&2
  fi
else
  echo "Not deploying $branch branch."
fi

echo "---- End of Git Post-Receive Hook ----"

exit 0

  • 关键命令：
    git --work-tree=/root/docker/nginx/html/yozuru.cn --git-dir=/home/hexo/repo/blog.git checkout -f
    • checkout：将Git仓库中的文件检出到指定的工作目录
    • -f：强制检出，覆盖工作目录中的文件
    • --work-tree：指定工作目录，存放网页静态文件的文件夹
    • --git-dir：指定Git仓库的路径
  • sudo /usr/bin/docker exec nginx nginx -s reload：重启Nginx服务
    • 这里是通过Docker部署的Nginx服务，所以需要执行docker exec命令来重启Nginx服务
    • 如果是其他方式部署、或使用了其他的静态服务器，则需要修改为对应的重载命令

给post-receive文件以可执行权限

1
chmod +x post-receive

配置SSH连接

  1. 进入git用户目录/home/hexo，创建文件夹.ssh，进入该文件夹创建文件authorized_keys
1
2
3
4
cd /home/git
mkdir .ssh
cd .ssh
vi authorized_keys
  • 注意，要以hexo用户执行以上命令
  1. 把本地的SSH公钥粘贴进去。

修改文件权限

1
2
3
4
# 需要权限
chown git:git /home/git/.ssh/authorized_keys
chmod 600 /home/git/.ssh/authorized_keys
chmod 700 /home/git/.ssh

完成后，在本地主机就可实现免密操作git了。

配置visudo

上述的post-receive文件中有两行关键命令是需要使用sudo权限的，所以需要配置sudo权限。
切换到root用户，执行以下命令

1
2
export EDITOR=/usr/bin/vim
visudo

找到类似 root ALL=(ALL:ALL) ALL 的行，在其下方或文件末尾添加以下两行。

1
2
hexo ALL=(ALL) NOPASSWD: /usr/bin/git --work-tree=/root/docker/nginx/html/yozuru.cn --git-dir=/home/hexo/repo/blog.git checkout -f
hexo ALL=(ALL) NOPASSWD: /usr/bin/docker exec nginx nginx -s reload

这样就可以让hexo用户获得执行post-receive脚本的权限了。

  • 测试一下是否成功

    1
    sudo -u hexo /usr/bin/docker exec nginx nginx -s reload

配置HEXO

修改Hexo工程根目录下的_config.yml文件，配置部署的参数

1
2
3
4
deploy:
  type: git
  repository: git@<你的服务器ip>:<刚创建仓库的路径>
  branch: main

  • type ：部署类型，这里固定填git

  • repository：仓库地址，换成自己仓库的SSH访问地址比如本次的git@<你的服务器ip>:/home/hexo/repo/blog.git

  • branch：分支名，填写main即可

修改完后在本地执行hexo d，如果提示成功了，则Hexo会通过git将博客部署到服务器上。

此时连接服务器打开你存放网页静态文件的文件夹，查看是否有文件，看和本地hexo下public里的内容是否一致。

此后，更新博客内容只需要在本地执行以下命令即可。

1
2
3
hexo clean
hexo generate
hexo deploy

补充

多端部署

刚才介绍了两种部署方案，各有优劣，那么这两种部署方式可以同时实现吗？当然可以。只需要修改Hexo的配置文件即可：

1
2
3
4
5
6
7
8
deploy:
  - type: git
    repository: git@github.com:Kagenui-yozuru/Kagenui-yozuru.github.io.git
    branch: main
  - type: git
    repository: git@<你的服务器ip>:<刚创建仓库的路径>
    branch: master
  - ……其它的部署方案

将前两种部署方案的配置以数组的形式整合进配置文件即可。这样在执行 hexo deploy时将会同时执行这两种部署操作。（我全都要）

Hexo源文件的版本控制

因为从Hexo源文件到静态网页文件这个过程是不可逆的，所以如果本地的Hexo源文件丢失，博客数据将无法恢复。以防万一还是用Git对Hexo源文件进行一下版本控制。

先在GitHub上创建仓库 hexo-origin。

在Hexo根目录下创建.gitignore文件，写入以下内容

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
.deploy_git/
public/
.github/
db.json
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# next.js
/.next/
/out/

# production
/build

# misc
.DS_Store
*.pem

# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*

# local env files
.env*.local

# vercel
.vercel

# typescript
*.tsbuildinfo
next-env.d.ts
dev

.vscode
.idea

# docker-compose env files
.env

*.key
*.key.pub

在Hexo根目录下运行以下命令。

1
2
3
4
5
git init
git remote add origin <remote-url>
git add .
git commit -m "Initial commit"
git push -u origin main

这样每次部署的时候也更新一下这个仓库就可以了。

至此，基于Hexo + Git + Nginx|GitHub Pages 一键部署、更新博客的方案就完成了。
之后的更新只需要在本地执行以下命令即可。

1
2
3
hexo clean
hexo generate
hexo deploy

编写部署脚本

为了了方便部署，可以将上面的命令写成一个脚本，放在Hexo根目录下。

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
$ErrorActionPreference = "Stop"
$project_path = "D:\blog"

Set-Location -LiteralPath $project_path -ErrorAction Stop

# Execute Hexo commands
hexo clean -ErrorAction Stop
hexo generate -ErrorAction Stop
hexo algolia -ErrorAction Stop
hexo deploy -ErrorAction Stop

# Check for Git changes in the main repository
git diff --quiet
$gitStatusExitCode = $LASTEXITCODE

if ($gitStatusExitCode -eq 0) {
}
else {
    git add .

    $commitMessage = Read-Host -Prompt "请输入提交信息 (留空默认为 'chore: 自动同步')"

    if ([string]::IsNullOrWhiteSpace($commitMessage)) {
        $commitMessage = "chore: 自動同步"
    }

    git commit -m $commitMessage

    git push --recurse-submodules=on-demand
}

Read-Host -Prompt "按 Enter 键退出..."

这样就可以直接双击脚本文件来实现一键更新、部署了。