博客搭建：GitHub Pages + Hexo + Fluid

本文最后更新于：2021年6月10日 下午

搞技术的，没有一个自己的个人博客可能说不过去。有注意到最近一些访问的博客站点是使用 Hexo 来搭建的，看起来效果还不错。因此尝试用 Hexo 搭建一个静态的博客站点，再存放到 GitHub Pages 上。以下介绍的一些本地安装配置，均在 macOS 下操作。

前提

首先需要安装 Git 和 Node.js ，git 已经安装好了。Mac 下安装 Node.js 需要使用 Homebrew ，之前安装的 Homebrew 已经年久失修，还需要更新。顺带补充下 Homebrew 的安装与使用。

Homebrew 安装

  • Homebrew 官方网站

  • 安装XCode或者Command Line Tools for Xcode。Xcode 可以从 AppStore 里下载安装，Command Line Tools for Xcode需要在终端中输入以下代码运行安装：

    xcode-select --install

  • 安装 Homebrew。将以下命令粘贴至终端

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

    脚本会在执行前暂停，并说明将它将做什么。

    安装完成以后，需要运行brew doctor命令检测下是否有什么冲突的地方（如没有卸载MacPorts等等）

  • 基本使用

    # 搜索包
brew search mysql

# 安装包
brew install mysql

# 查看包信息，比如目前的版本，依赖，安装后注意事项等
brew info mysql

# 卸载包
brew uninstall wget

# 显示已安装的包
brew list

# 查看brew的帮助
brew –help

# 更新， 这会更新 Homebrew 自己
brew update

# 检查过时（是否有新版本），这会列出所有安装的包里，哪些可以升级
brew outdated
brew outdated mysql

# 升级所有可以升级的软件们
brew upgrade
brew upgrade mysql

# 清理不需要的版本极其安装包缓存
brew cleanup
brew cleanup mysql

  • brew update 时遇到的一些问题

    因为网络原因，brew update 会遇到执行出错的情况。

    • 下载失败

      解决方案，使用国内镜像。有阿里巴巴、中科大、清华等可选。但是在公司折腾了前两个都不行，换了环境之后才下载成功。归根结底可能是公司网络环境的原因，因此替换镜像的方法仅做参考。

      Zsh 终端配置：

      # 替换brew.git:
cd "$(brew --repo)"
git remote set-url origin https://mirrors.aliyun.com/homebrew/brew.git
# 替换homebrew-core.git:
cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
git remote set-url origin https://mirrors.aliyun.com/homebrew/homebrew-core.git
# 替换homebrew-bottles:
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.aliyun.com/homebrew/homebrew-bottles' >> ~/.zshrc
source ~/.zshrc
# 应用生效
brew update

#恢复默认配置
# 重置brew.git:
cd "$(brew --repo)"
git remote set-url origin https://github.com/Homebrew/brew.git
# 重置homebrew-core.git:
cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
git remote set-url origin https://github.com/Homebrew/homebrew-core.git

#删掉 HOMEBREW_BOTTLE_DOMAIN 环境变量，打开~/.zshrc，找到 HOMEBREW_BOTTLE_DOMAIN 这行并删除
source ~/.zshrc

    • “Checksum mismatch”

      解决方案，删除 `Archive:` 后面路径下的文件，然后再重新 update 。

      rm -rf /Users/aici/Library/Caches/Homebrew/portable-ruby--2.6.3.mavericks.bottle.tar.gz

Node.js 安装

  • 安装 Node.js

    brew install node

  • 版本验证

    #出现版本号即说明安装成功
node -v
npm -v

  • 更换 npm 源

    npm install -g cnpm --registry="https://registry.npm.taobao.org"
#出现结果即可证明更换成功
cnpm

Hexo 基础

  • 安装

    #全局安装，局部安装目前看没必要
npm install -g hexo-cli

  • 创建文件夹

    cd /usr/local
mkdir hexo

  • 初始化

    cd /usr/local/hexo
hexo init

  • 启动服务，打开 localhost:4000 即可看到 hexo 博客

    hexo s

主题

主题选择

  • Butterfly

    看起来功能完全覆盖了 Fluid，风格也是和 Fluid 类似的。配置文档太多了加上第一眼看到的是 Fluid，就放弃这个了。

  • Fluid

    先看到这个再看到的 ButterFly，功能看起来不如 ButterFly 丰富，不过第一眼印象还是更喜欢这个。

  • Ayer

    一个简洁也很漂亮的主题，也是让人纠结的选择。

  • Maupassant

    非常简洁的主题，不想用 NexT 的可以考虑试一试。

  • NexT

    几乎是见的最多的主题，我心中 Hexo 博客默认的样子。功能很多，样式也很全面，几乎是不会出错的选择。

配置

完成的配置指南参见：Fluid配置指南。下面仅列出一些关键配置。

获取最新版本

请优先下载 最新 release 版本，master 分支无法保证稳定。

下载后解压到 themes 目录下并重命名为 fluid。

必要的配置

必须如下修改博客目录下的 _config.yml：

theme: fluid  # 指定主题

language: zh-CN  # 指定语言，可不改
创建「关于页」

首次使用主题的「关于页」需要手动创建：

$ hexo new page about

创建成功后修改 /source/about/index.md，添加 layout 属性。

修改后的文件示例如下：

---
title: about
date: 2020-07-20 10:55:54
layout: about
---

# 这里可以写正文
支持 Markdown, HTML
覆盖配置

该功能可实现平滑升级主题，推荐所有人学习使用。

覆盖配置可以使主题配置放置在 fluid 目录之外，避免在更新主题时丢失自定义的配置。

使用该功能必须保证 Hexo 版本不低于 3.0，因为该功能利用了 Hexo 数据文件 功能。

使用方式：

  1. 进入博客目录的 source 目录下（不是主题目录的 source），创建 _data 目录（和 _post 目录同级）；
  2. 在 _data 目录下创建 fluid_config.yml 文件，将 /theme/fluid/_config.yml 中全部配置（或部分配置）复制到 fluid_config.yml 中；
  3. 以后配置都在 fluid_config.yml 中修改，配置会在 hexo g 时自动覆盖。

TIP

  • 也可以只覆盖部分配置，但注意只要存在于 fluid_config.yml 的配置都是高优先级，修改原 _config.yml 是无效的。
  • 每次更新主题可能存在配置变更，请注意更新说明，可能需要手动对 fluid_config.yml 同步修改。
  • 想查看覆盖配置有没有生效，可以通过 hexo g --debug 查看命令行输出。

如果想将某些配置覆盖为空，注意不要把主键删掉，不然是无法覆盖的，比如：

about:
  icons:  # 不要把 icon 注释掉，否则无法覆盖配置
    # - { class: 'iconfont icon-github-fill', link: 'https://github.com' }
    # - { class: 'iconfont icon-wechat-fill', qrcode: '/img/favicon.png' }
博客标题

页面左上角的博客标题，默认使用博客配置中的 title，这个配置同时控制着网页在浏览器标签中的标题。

如需单独区别设置，可在主题配置中设置：

navbar:
  blog_title: 博客标题
统计 PV 与 UV

页脚可以展示 PV 与 UV 统计数据，目前支持两种数据来源：LeanCloud 与 不蒜子。此处使用 LeanClound，需要注册后填写相关配置才生效。

  • 注册 LeanClound 账号
  • 创建应用
  • 将应用的 AppId、 AppKey 和 REST API 服务器地址粘贴到 web_analytics 下对应位置
  • 创建 Class 存储访问量等数据
  • footer.statistics.source 填写 leancloud
首页 Slogan（打字机）

首页大图中的打字机文字，可在主题配置中设定是否开启：

index:
  slogan:
    enable: true
    text: 这是一条 Slogan

如果 text 为空则按博客配置的 subtitle 显示。

相关的打字机动效设置在：

fun_features:
  typing: # 为 subtitle 添加打字机效果
    enable: true
    typeSpeed: 70 # 打印速度
    cursorChar: "_" # 游标字符
    loop: false # 是否循环播放效果

并不是很喜欢打字效果，直接关闭了。

文章摘要

开关自动摘要（默认开启）：

index:
  auto_excerpt:
    enable: true

若要手动指定摘要，使用 <!-- more --> MD 文档里划分，如：

这里是摘要
<!-- more -->
这里是正文

按照配置文档里使用 <!-- more --> 后会报错，并且摘要未生效。如果配置 Front-matter 可以解决。未配置 Front-matter 时，也可以通过添加 —- 水平线解决，没有查到相关文档的解释。

或者在 Front-matter 里设置 excerpt 字段，如：

---
title: 这是标题
excerpt: 这是摘要
---

TIP

优先级: 手动摘要 > 自动摘要

如果关闭自动摘要，并且没有设置手动摘要，摘要区域空白

无论哪种摘要都最多显示 3 行，当屏幕宽度不足时会隐藏部分摘要。

文章内容图片

本地图片存放位置同上。

![](/img/example.jpg)
日期/字数/阅读时长/阅读数

显示在文章页大标题下的文章信息，除了阅读次数，其他功能都是默认开启的。

post:
  meta:
    date:  # 日期
      enable: true
      format: "dddd, MMMM Do YYYY, h:mm a"  # 格式参照 ISO-8601 日期格式化
    wordcount:  # 字数统计
      enable: true
      format: "{} 字"  # 显示的文本，{}是数字的占位符（必须包含)，下同
    min2read:  # 阅读时间
      enable: true
      format: "{} 分钟"
    views:  # 阅读次数
      enable: false
      source: "leancloud"  # 统计数据来源，可选：leancloud | busuanzi   注意不蒜子会间歇抽风
      format: "{} 次"
评论

开启评论需要在主题配置中开启并指定评论模块：

post:
  comments:
    enable: true
    type: valine

比较推荐的主要是两个：utterances 和 valine。此处使用 valine，据说配置方便又简约，基于 Leancloud 的无后端设计。

  • 请先登录或注册 LeanCloud, 进入控制台后点击左下角创建应用
  • 应用创建好以后，进入刚刚创建的应用，选择左下角的设置>应用Key，然后就能看到你的APP ID和APP Key了
  • 创建 Class 存储评论数据
  • 将应用的 AppId、 AppKey 和 REST API 服务器地址粘贴到 valine 下对应位置
  • 其他配置视情况需要修改
脚注

主题内置了脚注语法支持，可以在文章末尾自动生成带有锚点的脚注，该功能在主题配置中默认开启：

post:
  footnote:
    enable: true
    header: ''

脚注语法如下：

这是一句话[^1]
[^1]: 这是对应的脚注

更优雅的使用方式，是将脚注写在文末，比如：

正文

## 参考
[^1]: 参考资料1
[^2]: 参考资料2

当然你也可以通过修改上方配置项 header 来自动加入节标题，如下所示：

post:
  footnote:
    enable: true
    header: '<h2>参考</h2>'  # 等同于手动写 `## 参考`
分类和标签

只有文章支持分类和标签，您可以在 Front-matter 中设置。在其他系统中，分类和标签听起来很接近，但是在 Hexo 中两者有着明显的差别：分类具有顺序性和层次性，也就是说 Foo, Bar 不等于 Bar, Foo；而标签没有顺序和层次。

categories:
- Diary
tags:
- PS3
- Games

分类方法的分歧

如果您有过使用 WordPress 的经验，就很容易误解 Hexo 的分类方式。WordPress 支持对一篇文章设置多个分类，而且这些分类可以是同级的，也可以是父子分类。但是 Hexo 不支持指定多个同级分类。下面的指定方法：

categories:
  - Diary
  - Life

会使分类Life成为Diary的子分类，而不是并列分类。因此，有必要为您的文章选择尽可能准确的分类。

如果你需要为文章添加多个分类，可以尝试以下 list 中的方法。

categories:
- [Diary, PlayStation]
- [Diary, Games]
- [Life]

此时这篇文章同时包括三个分类： PlayStation 和 Games 分别都是父分类 Diary 的子分类，同时 Life 是一个没有子分类的分类。

部署

创建仓库

在 github 上创建博客的仓库，创建仓库地址：https://github.com/new。如果你希望你的站点能通过 <你的 GitHub 用户名>.github.io 域名访问，你的 repository 应该直接命名为 <你的 GitHub 用户名>.github.io。

一键部署

  • 修改博客目录下的 _config.yml

    deploy:
  type: git
    repo: https://github.com/<你的 GitHub 用户名>/<你的 GitHub 用户名>.github.io
  branch: master

    TIP

    官方教程有坑！

    - github.com/username/username.github.io 这样的仓库用master分支

    - github.com/username/cengjingbeikengguo 这样的用gh-pages

  • 安装 hexo-deployer-git，使用 cnpm

    $ cnpm install hexo-deployer-git --save

  • 生成站点文件并推送至远程库。 hexo clean && hexo deploy

    $ hexo clean && hexo deploy

  • 登入 Github，请在库设置（Repository Settings）中将默认分支设置为 _config.yml 配置中的分支名称。稍等片刻，您的站点就会显示在您的 Github Pages 中。

日常使用

创建新文章

# 创建新文章
hexo new "xxx xxx xxx"

# 测试
hexo s

# 生成站点并部署
hexo d -g

更新 hexo 及插件

更新 hexo

npm update -g hexo

更新插件

npm update

更换电脑

  • 使用 git 同步
  • 使用坚果云选择性同步这几个文件夹。然后在另一台电脑上搭建博客环境、安装相关插件后。同步这些文件，然后重新生成、部署站点。

提交到 Google 收录

网址验证

  1. 进入Google Search Console 登录你的谷歌账号

  2. 在网址前缀中填写地址

  3. 下载验证文件

  4. 拷贝到你的本地博客 hexo/sources/ 下

    注意：hexo在部署source 文件夹下markdown语法格式的文件成html格式时（本身文件格式就是html格式），都会遵守固有的html布局格式，所以后面Google验证html文件时，此时的“html验证文件”已经不是原本下载的文件，变成遵守固有布局的html文件，为了正常验证步骤进行，部署服务器前必须先打开“html验证文件“，加入以下内容，让固有的html布局失效。

    >layout: false
>---

  5. 部属到 GitHub 远程仓库

    hexo g -d

  6. 本地操作完成后，继续返回到网站页面，点击验证，成功！

生成站点地图

在本地 Hexo 博客根目录下安装 sitemap 生成插件

npm install hexo-generator-sitemap --save

编辑站点目录下的_config.yml 配置文件，添加以下字段：

# 自动生成sitemap
sitemap:
  path: sitemap.xml
# 修改url为网站地址
url: https://popesaga.github.io/

部署到远程仓库

$ hexo g -d

添加站点地图

这时在远程仓库根目录就可以看到sitemap.xml文件了。
返回谷歌站点地图，选择已经验证过的站点，在站点地图 中，添加新的站点地图，添加 sitemap.xml 的链接。

添加成功后等待 google 收录即可。

杂七杂八
GitHub Hexo Fluid Homebrew

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！