Hexo 静态博客指南：建站教程（上）

本文最初发布于我的个人博客Bambrow’s Blog，采用 BY-NC-SA 许可协议，转载请注明出处。若有后续更新，将更新于原博客。欢迎去我的博客阅读更多文章！

本文详细记录一下站点建立过程，以便查阅。对于具体的细节则不会做过多解释，主要展示步骤。这一篇主要讲述准备工作、首次部署与自动部署的相关内容。

本文运行环境：

node: v14.4.0
npm: 6.14.7
hexo: 4.2.1
hexo-cli: 3.1.0

准备工作

准备工作主要参考了Hexo官方文档。

安装Git与Node.js

在Mac上最方便的方法当然是通过Homebrew。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

注意，可能在安装之前需要先安装Command Line Tools for Xcode。直接在终端输入xcode-select --install安装。

安装好Homebrew后，直接使用以下命令：

brew install git
brew install node

在安装以上两个依赖之前，可以先运行brew update来更新Homebrew。此外，还可以运行brew doctor检查一下有没有什么冲突，可以及时处理。也可以把以下语句加入你的.bash_profile或者.zshrc，取决于你使用的shell：

export PATH="/usr/local/bin:$PATH"

安装好后，可以用以下命令查看是否安装成功，成功则会返回版本号：

git --version
npm -v

安装Hexo

直接使用npm安装：

npm install -g hexo-cli

查看一下hexo是否安装成功，会返回当前的hexo版本号：

hexo -v

注册GitHub并新建个人仓库

GitHub就不用多说了。注册完成后，新建公有仓库，名称为你的GitHub用户名.github.io。这个仓库用来存放渲染好的页面。

此外，我们再新建一个私有仓库，用来存放源文件本身。仓库的名字任意取，我取的名字是blog。

这两个仓库最好不要初始化任何东西，也就是README，.gitignore和license都不要。这样新建的仓库完全是空的。

设置Git与密钥文件

首先运行以下两句进行Git配置：

git config --global user.name "GitHub用户名"
git config --global user.email "GitHub注册邮箱"

其中把用户名和邮箱替换成你自己的。然后我们生成密钥文件：

ssh-keygen -t rsa -C "GitHub注册邮箱"

直接一路回车下去就好，结束后会在~/.ssh/文件夹里生成id_rsa私钥文件与id_rsa.pub公钥文件。我们读取一下公钥的内容并且手动拷贝：

cat ~/.ssh/id_rsa.pub

手动复制显示的内容。随后打开这个页面设置SSH Key。你也可以在GitHub主页点击你的右上角头像，选择Settings，然后选择SSH and GPG Keys找到这个界面。点击New SSH Key，标题可以随便写，内容就是你刚才复制的公钥内容，随后保存。

开始建站

博客初始化

首先选择一个你喜欢的地方作为你的博客根目录。

mkdir ~/git/你的GitHub用户名.github.io

随后按照官方教程，依次运行：

hexo init ~/git/你的GitHub用户名.github.io
cd ~/git/你的GitHub用户名.github.io
npm install

现在博客已经初始化完成了。使用以下命令：

hexo server

就可以在http://localhost:4000看到你的站点了。可以在终端里使用control+c关掉本地服务器。下面列举一些常用的命令，更多命令与参数可以参考这里：

• hexo clean 用于清除缓存与静态文件。
• hexo new "文章标题" 用于新建文章。
• hexo server 用于启动本地服务器查看渲染好的网页，可简写为hexo s。
• hexo generate 用于生成静态文件，可简写为hexo g。
• hexo deploy 用于部署网站，需要先设置好_config.yml，可简写为hexo d。

设置_config.yml

首先，可以参考官方的设置页面，这里只涉及一些核心设置。

用你喜欢的编辑器打开根目录下的_config.yml（注意不是themes文件夹里面的_config.yml）。

在Site下面你可以更改网页的标题、副标题、描述、作者、语言、时区等等。语言这里选择zh-CN。在URL下面可以把url改为你的GitHub Pages的URL，https://你的GitHub用户名.github.io。中间的大部分设置跳过，你也可以参照上面的网页进行修改。

最后，我们重点关注一下# Deployment。在这里，我们需要把它改为如下的样式：

deploy:
  type: git
  repo: 你的GitHub目录地址
  branch: master

其中repo要根据自己的情况修改。你可以在GitHub主页点击你的头像，选择Your repositories，点击你的你的GitHub用户名.github.io仓库，点击Code按钮，然后点击Use SSH（如果目前显示为Clone with HTTPS），然后复制框中的内容到这里。

修改好后，保存文件。

首次部署

我们需要再安装一个依赖：

npm install hexo-deployer-git --save

随后一切就绪，依次运行：

hexo clean
hexo g
hexo d

然后你就可以在https://你的GitHub用户名.github.io看到渲染好的网页了。

设置自动部署

在这一步里我们不仅备份了博客的源文件，也实现了修改push到blog私有仓库后触发GitHub Actions完成自动部署。

将源文件备份至私有仓库

在终端，自己的GitHub用户名.github.io文件夹内，手动添加远程仓库：

git init
git remote add origin [email protected]:bambrow/blog.git

这里的远程仓库就是你的blog仓库。把上面的[email protected]:bambrow/blog.git修改成你自己的仓库地址。方法同样是在网页进入blog仓库，点击Code按钮，然后点击Use SSH（如果目前显示为Clone with HTTPS），然后复制框中的内容到这里。

随后我们编辑一下.gitignore文件。可以使用你喜欢的编辑器。一般来讲，.gitignore应该有如下内容：

.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/

编辑好之后，先做：

git pull origin master

随后把所有应该备份的文件push到GitHub：

git add .
git commit -m "initial commit"
git push origin master

此时去GitHub上查看blog仓库，会发现内容已经更新。

设置GitHub Actions

请注意，在做这一步之前，请务必确认自己的blog仓库是私有仓库，如果不是，一定要在设置里将其设置为私有。

之前建立好的密钥文件，有公钥也有私钥。我们已经用过了公钥，这次使用私钥。首先读取其内容并手动拷贝：

cat ~/.ssh/id_rsa

手动复制全部内容。随后在网页上打开自己的blog仓库，点击Settings，再点击左侧的Secrets，随后新建。名称可以随意写，这里推荐HEXO_DEPLOY_KEY；内容则是刚才复制的私钥全部内容。随后点击添加。

随后，我们开始设置工作流。点击你的仓库标签下的Actions，选择新建New workflow。随后选择set up a workflow yourself，将main.yml的内容替换如下，你也可以自行修改：

# 工作流名称
name: Hexo Blog Deploy

# 只在push到master分支的时候启动
on:
  push:
    branches:
      - master

# 使用ubuntu虚拟机
jobs:
  build:
    runs-on: ubuntu-latest

    # 工作流步骤
    steps:
    - name: Checkout repository master branch
      uses: actions/checkout@master
      with:
        submodules: true

    # 安装Node.js
    - name: Install node.js
      uses: actions/setup-node@master
      with:
        node-version: "10.x"

    # 安装Hexo
    - name: Install hexo
      run: |
        npm install hexo-cli -g
        npm install

    # 设置SSH密钥，读取HEXO_DEPLOY_KEY
    - name: Setup private key
      env:
        HEXO_DEPLOY_KEY: ${{ secrets.HEXO_DEPLOY_KEY }}
      run: |
        mkdir -p ~/.ssh/
        echo "$HEXO_DEPLOY_KEY" > ~/.ssh/id_rsa
        chmod 600 ~/.ssh/id_rsa
        ssh-keyscan github.com >> ~/.ssh/known_hosts

    # 配置Git设置
    - name: Setup git settings
      run: |
        git config --global user.name "GitHub用户名"
        git config --global user.email "GitHub邮箱"
    # 更改上面的用户名和邮箱

    # 部署
    - name: Deploy hexo
      run: |
        hexo clean
        hexo generate
        hexo deploy

随后点击Start commit结束设置。这样以后只要有新的改动被push到blog的主分支，就后触发这个工作流，将网页渲染出来，同时也会push到你的GitHub用户名.github.io这个仓库里。

安装Markdown语法扩展

Hexo原生的Markdown渲染插件支持的Markdown语法不够丰富，比如不支持GitHub Flavored Markdown、CommonMark、上标下标、脚注等等。因此，我们在写文章之前，可以把原生的插件hexo-renderer-marked改为hexo-renderer-markdown-it。

首先，根据该插件的安装指南，运行以下命令：

npm uninstall hexo-renderer-marked
npm install hexo-renderer-markdown-it

随后在_config.yml里添加如下语句（可以添加在deploy前面）：

# Markdown-it config
## Docs: https://github.com/celsomiranda/hexo-renderer-markdown-it/wiki
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  plugins:
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup
  anchors:
    level: 2
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: header-anchor
    permalinkSide: 'left'
    permalinkSymbol: ¶

随后你就可以使用扩展语法了。使用方法可以参看这里和这里，尤其是后一个网页给出了很详细的例子。

如果你觉得脚注字体偏大，可以看我的字体设置文章，看完后就知道怎么修改了。我个人做了如下设置：

.footnotes {
    font-size: 75%;
}

因为我们引入了新的插件，所以也要改一下工作流文件，在安装Hexo那一步加一些步骤，安装这些依赖。你可以在本地修改.github/workflows/main.yml的内容，也可以在GitHub的blog仓库，点击Actions，选择最近的一次部署，点击右侧的省略号中的View workflow file，然后点击右侧的铅笔按钮进行修改。将新的依赖安装写在npm install那一行后面即可。如果你采用后者，在你将本地新的改动push到GitHub之前，要记得先做git pull，否则会报错显示远程仓库有新的改动。推荐在本地修改，一步到位。

  run: |
    npm install hexo-cli -g
    npm install
  + npm uninstall hexo-renderer-marked
  + npm install hexo-renderer-markdown-it