使用Hexo搭建自己的博客网站

1. 背景介绍

本文是写给完全没有接触过技术的普通博客用户使用的，所以解释地比较细致，如果有技术基础，可以忽略其中的解释部分，按命令执行即可．
说明：我的工作环境是 fedora linux, 出于安全性考虑一直运行在普通用户下, 如果你的安装环境是 Mac 或者 windows，请理解每一步骤的含义后执行调整命令和参数.
或者在我的博客下面留言，我有空的时候会统一回复．
说说我为什么选择 Hexo, 目前比较主流的博客生成系统有三个 hexo, jekyll 和 hugo，jekyll 是老牌的博客生成系统，受到了 github 官方的支持，但是是用的 ruby 的技术栈，
我是技术出生, 但是 ruby 一直不在我的技术栈范围之内，至于 jekyll 和 github 在部署的时候的结合度更高的问题，我想对于一个做技术的人来说应该不是什么难事，应该比较容易解决．
相比之下 hexo 使用的 nodejs 技术栈，hugo 是 golang 技术栈这两块技术栈我都比较熟悉，主要在这两个博客生成器系统之间徘徊．hugo 固然速度更快，github 上获得的星星数量也更多一些．由于考虑到博客系统更偏向于前端技术，这一块为 nodejs 所擅长，很多库都可以重用。从自己的职业嗅觉，我觉得一个静态博客系统或博客生成器采用 nodejs 技术栈更合适一点，另外很重要的一点 Hexo Theme 显得更成熟一些，所以我选择 Hexo, hexo 和 hugo 现在也很难说谁会在这一领域最终胜出．经过调查发现即使将来 hugo 胜出，迁移到 hugo 成本也不会太高．就我目前的个人需求和兴趣点来说，我还是比较偏向 Hexo.

本文原文位于使用 Hexo 搭建自己的博客网站, 如需获取最近更新，以及遇到 markdown 排版问题，请访问原文，以获得最佳阅读体验。

2. 前提条件

需要先安装 nodejs 的相应版本
发布博客需要注册 github 账号

3. 安装 Hexo

在安装 Hexo 首先需要了解 hexo 版本与 nodejs 版本的兼容性，避免安装之后出现版本兼容性问题。
详情参考Install-Hexo。

Hexo version	Minimum (Node.js version)	Less than (Node.js version)
7.0+	14.0.0	latest
6.2+	12.13.0	latest
6.0+	12.13.0	18.5.0
5.0+	10.13.0	12.0.0
4.1 - 4.2	8.10	10.0.0
4.0	8.6	8.10.0
3.3 - 3.9	6.9	8.0.0
3.2 - 3.3	0.12	unknown
3.0 - 3.1	0.10 or iojs	unknown
0.0.1 - 2.8	0.10	unknown

3.1. 安装 nodejs

首先需要安装 nodejs, 可以参考我以前写的一篇博文安装并配置 nodejs，需要从以上表格中找到对应的版本进行替换。

3.2. 安装 Hexo 命令行工具


   sudo npm install hexo-cli -g
  　或者
   #（推荐使用cnpm安装, 速度快）
   sudo cnpm install hexo-cli -g

说明:
npm 是 nodejs 的包管理工具，sudo 是 linux 或 unix 下将命令以管理员身份运行, windows 环境下不需要 sudo,

install 为 npm 子命令用于安装工具包或项目依赖

-g 为全局安装，安装一次后，在命令行中处于任何目录位置都能使用，如果不带-g 工具包被安装在当前项目的 node_modules，

需要借助 npx 才能执行相关命令，像 hexo-cli 这样的命令行工具建议全局安装

这一步需要管理员权限，sudo 即为以超级用户运行安装命令，linux 和 mac 安装方法相同

如果是 windows 环境可能需要以管理员身份运行，可以将 sudo 去掉, windows 下如果需要管理员权限,会弹出请求授权框
即 npm install hexo-cli -g 或者 cnpm install hexo-cli -g

如果访问墙外资源较慢，可以是 cnpm 经过阿里的镜像安装 hexo-cli 命令行工具，cnpm 前面的 c 即为 china 的意思，wall 内专用 nodejs 包管理工具

4. 创建博客系统

4.1. 初始化博客系统

# 创建博客目录(blog为目录名,可以根据自己的喜好进行调整)
mkdir blog

# 进入博客目录
cd blog

# 初始化hexo
hexo init blog

命令说明：

hexo: 是 hexo 的命令

init: hexo 的子命令，用于初始化一个博客系统．

blog: 是博客系统的名字，这里我没有考虑太多，直接将博客系统的名字命名为 blog,　你可以根据自己的喜好设定名字．

进入 blog 目录，安装项目依赖包(第三方 nodejs 类库或工具)

# 安装nodejs依赖包
npm install

初始化完成后的简要目录结构如下:

./blog
    ├── _config.landscape.yml
    ├── _config.yml
    ├── db.json
    ├── node_modules
    ├── package.json
    ├── package-lock.json
    ├── scaffolds
    ├── source
    └── themes

4.1.1. 目录结构说明

package.json: 这个是 nodejs 要用到的，里面存放着项目信息，版本，项目所依赖的第三方 nodejs 工具和代码库
package-lock.json: 这个 nodejs 解析依赖包时会用到的
scaffolds: 博客脚手架，当你创建新的博文时可以基于其中的某个模板进行修改．
source: 源代码文件夹，这里存放你网站的内容．
themes: 主题，博客 css 样式，背景图片等等．
node_modules: 这里存放 npm install 时从网络下载下来的依赖包
config.yml 项目配置文件

配置文件详细说明

这里重点说明一下项目配置文件．

你可以修改项目的默认配置文件_config.yml 以满足你个人的需求．比如标题，网站的描述，搜索关键字等等一些信息

| setting        | chinese          | desc             |
| :------------- | :-------------- | :--------------- |
| title 　　     | 标题 　　　　   | 你网站的标题     |
| subtitle 　    | 子标题 　　　   | 你网站的子标题   |
| description 　 | 网站描述 　　　 | 你网站的描述信息 |
| keywords 　    | 关键字 　　　   | 关键字　         |
| author 　      | 作者 　　　     | 网站的作者       |
| language 　    | 语言            | 网站支持的语言   |
| timezone 　    | 网站时区 　　　 | 网站时区         |
| theme    　    | 主题     　　　 | 使用的主题名称   |
| per_page 　    | 每页文章数量    | 每页显示的文章量 |
| pagination_dir | 分页url        | 指定博客生成后，每页的 index.html 文件存放目录 |

5. 本地启动博客系统

当前目录下执行以下命令，启动博客系统.

　hexo serve

如果启动成功，会输出以下信息，最后一行会提示，通过什么网址可以访问博客．
打开浏览器，将网址粘贴到浏览器即可访问到博客系统．

$hexo serve
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

使用浏览器打开http://localhost:4000
打开博客首页会看到一些默认的博客页面，后面我们将会讲解如何修改代码来构建自己的博客系统．

6. 创建第一篇博文

将一篇 markdown 格式的文章拷贝到 source 目录下，在博文开头加上标题，日期，标签页．
刷新浏览器，即可看到自己的第一篇博客文章．

创建一篇博文, 向世界宣布你来了.

---
title: 使用Hexo搭建自己的博客网站
date: 2021/10/4
tags:
  - Hexo
categories:
  - blog
---

## first blog

hello world!

7. 如何发布博客

7.1. 创建 github 代码仓库

创建一个以你的 github 用户名命名的代码仓库例如 xxxx.github.io,

7.2. 安装 deployer 插件并配置 deploy

安装 hexo-git plugin

  npm install hexo-deployer-git --save
  或者
  cnpm install hexo-deployer-git --save　//推荐

修改配置文件_config.yml 配置 deploy

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  - type: git
    repo: [email protected]:your_github_id/xxxx.github.io.git
    branch: gh-pages
    name: yourname
    email: [email protected]

说明: 这里的 url 可以是 http https 也可以是 git url 但是建议使用 git url
实测在 push 文件到 github 时使用 https 路径，经常会有异常抛出，使用 git url 后比较稳定
使用 https url 需要在 url 上添加授权方式和 token 像这样 repository: https://oauth2:[email protected]/*****.github.io, 实测可行 on Nov 1 2021

为了防止将一些非必要的文件推送到 github 仓库，创建一个.gitignore 文件, 内容如下：

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

7.3. 创建 gitHub token

打开自己的 GitHub 主页，点击自己的头像找到 Settings 并进入, 选择 developer settings 在左边目录栏找到 Personal access tokens，点击 Generate new token，按照步骤申请即可，过程比较简单, 这里不详述。
Scopes（范围）只需要授权 repo:status 和 repo:public_repo 权限即可。Token 申请成功后，将 Token 复制并保存起来．当运行发布命令时需要输入此 token 作为密码

这样前期准备工作基本完成，现在开始发布博客。
发布博客系统使用如下命令:

  hexo clean && hexo generate && hexo deploy

当提示输入 git 用户名密码时，输入你的 github 用户名, 当提升输入密码时，输入上面生成的 token

7.4. 验证发布是否成功

浏览器打开自己的博客首页 https://xxxx.github.io/

由于我设置了 dns cname 所以实际会跳转到https://pengtech.net/

回头看一下 hexo 上传了哪些文件到 github, 其实只是上传了编译后的文件

所以需要自己将源文件保存到一个私有仓库，或者上传到另一个 github 仓库

  2021/10/04/post
  archives
  css
  fancybox
  js
  tags/Hexo
  index.html

8. 选择一个漂亮的主题

可以参考我的文章，里面有 10 多款精美的主题可供选择16 款精美的 hexo 博客主题推荐 | 鹏叔的技术博客

9. 进阶: 如何开启评论, 转发, 优化界面等等

可以参考我的文章 Hexo 博客添加评论功能 | 鹏叔的技术博客

更多 Hexo 相关主题可以访问我的博客 hexo 主题https://pengtech.net/hexo/

10. 插入图片

Markdown 并不会保存插入的图片资源本身，只是记录了获取资源的链接。因此我们需要选择一款合适的图床来支持博客写作，目前各大云服务商都提供了对象存储服务，如七牛云 KODO、又拍云 USS、腾讯云 COS、阿里云 OSS 等。

可以使用PicGo工具上传图片到图床上。

11. 进阶: SEO 优化

可以参考我的文章 Hexo 博客搜索引擎优化| 鹏叔的技术博客

12. 文章置顶

这一功能已被加入 hexo-generator-index。之前老的方法使用 hexo-generator-index-pin-top 替换 hexo-generator-index, 这种不要再参考了, pin-top 已经八年没有更新了. 详细使用方法可以参考 hexo-generator-indexed

在文章的 Front-matter 中增加一个 sticky 参数用来置顶，其值应为大于 0 的整数，表示置顶的优先级（未指定则默认为 0）。数字越大，文章越靠前。

---
title: example
sticky: 100
---

13. 相关阅读

14. 参考文档

Hexo 官方文档

Hexo 配置文档

hexo 博客文章置顶功能实现的两种方法

15. trouble shooting

问题: 启动时遇到 err: Error: ENOSPC: System limit for number of file watchers reached

具体错误信息如下

    $hexo server
    INFO  Validating config
    INFO  Start processing
    FATAL {
    err: Error: ENOSPC: System limit for number of file watchers reached, watch '$your_project_dir/blog/source/'
    at FSWatcher.<computed> (internal/fs/watchers.js:218:26)
    at Object.watch (fs.js:1582:34)
    at createFsWatchInstance ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:119:15)
    at setFsWatchListener ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:166:15)
    at NodeFsHandler._watchWithNodeFs ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:331:14)
    at NodeFsHandler._handleDir ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:559:19)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async NodeFsHandler._addToNodeFs ($your_project_dir/blog/node_modules/chokidar/lib/nodefs-handler.js:609:16)
    at async $your_project_dir/blog/node_modules/chokidar/index.js:451:21
    at async Promise.all (index 0) {
    errno: -28,
    syscall: 'watch',
    code: 'ENOSPC',
    path: '$your_project_dir/blog/source/',
    filename: '$your_project_dir/blog/source/'
    }
    } Something's wrong. Maybe you can find the solution here: %s https://hexo.io/docs/troubleshooting.html

解决办法

扩大能 watch 的文件数上限

  echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

问题: The TLS connection was non-properly

  fatal: unable to access 'https://github.com/xxxx/xxxx.github.io/': gnutls_handshake() failed: The TLS connection was non-properly terminated.
  FATAL {
  err: Error: Spawn failed
  at ChildProcess.<anonymous> ($your_project_dir/blog/node_modules/[email protected]@hexo-util/lib/spawn.js:51:21)
  at ChildProcess.emit (events.js:400:28)
  at Process.ChildProcess._handle.onexit (internal/child_process.js:277:12) {
  code: 128
  }
  } Something's wrong. Maybe you can find the solution here: %s https://hexo.io/docs/troubleshooting.html

原因分析

其实出现这个问题，很大可能是因为 https 和 http 的 proxy 的对应的分别是 https 和 http 开头的 proxy server，而 https 的 proxy server 可能无法正常工作。一个 workaround 是把 https 的 proxy server 换成 http 的 proxy server: