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

1. 背景介绍

  • 本文是写给完全没有接触过技术的普通博客用户使用的,所以解释地比较细致,如果有技术基础,可以忽略其中的解释部分,按命令执行即可.

  • 说明:我的工作环境是 deepin 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. 前提条件

  1. 需要先安装 nodejs 的相应版本

  2. 发布博客需要注册 github 账号

3. 安装 Hexo

在安装 Hexo 首先需要了解hexo版本与nodejs版本的兼容性,避免安装之后出现版本兼容性问题。

Hexo versionMinimum (Node.js version)Less than (Node.js version)
7.0+14.0.0latest
6.2+12.13.0latest
6.0+12.13.018.5.0
5.0+10.13.012.0.0
4.1 - 4.28.1010.0.0
4.08.68.10.0
3.3 - 3.96.98.0.0
3.2 - 3.30.12unknown
3.0 - 3.10.10 or iojsunknown
0.0.1 - 2.80.10unknown
  • 首先需要安装 nodejs, 可以参考我以前写的一篇博文安装并配置 nodejs,需要从以上表格中找到对应的版本进行替换。

  • 安装 Hexo 命令行工具

    1
    2
    3
    4
    5
    6

    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. 创建博客系统

  • 初始化博客系统

    1
    2
    3
    4
    5
    6
    7
    8
    # 创建博客目录(blog为目录名,可以根据自己的喜好进行调整)
    mkdir blog

    # 进入博客目录
    cd blog

    # 初始化hexo
    hexo init blog

    命令说明:

    hexo: 是 hexo 的命令

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

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

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

    1
    npm install

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

1
2
3
4
5
6
7
8
9
10
./blog
├── _config.landscape.yml
├── _config.yml
├── db.json
├── node_modules
├── package.json
├── package-lock.json
├── scaffolds
├── source
└── themes

-目录结构说明

  • package.json: 这个是 nodejs 要用到的,里面存放着项目信息,版本,项目所依赖的第三方 nodejs 工具和代码库

  • package-lock.json: 这个 nodejs 解析依赖包时会用到的

  • scaffolds: 博客脚手架,当你创建新的博文时可以基于其中的某个模板进行修改.

  • source: 源代码文件夹,这里存放你网站的内容.

  • themes: 主题,博客 css 样式,背景图片等等.

  • node_modules: 这里存放 npm install 时从网络下载下来的依赖包

  • config.yml 项目配置文件

  • 配置文件详细说明

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

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

      settingchinesdesc
      title标题你网站的标题
      subtitle子标题你网站的子标题
      description网站描述你网站的描述信息
      keywords关键字关键字
      author作者网站的作者
      language语言网站支持的语言

5. 本地启动博客系统

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

1
 hexo serve

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

1
2
3
4
$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 目录下,在博文开头加上标题,日期,标签页.
刷新浏览器,即可看到自己的第一篇博客文章.

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

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 使用Hexo搭建自己的博客网站
date: 2021/10/4
tags:
- Hexo
categories:
- blog
---

## first blog

hello world!

7. 将博客发布到 github

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

  • 修改配置文件_config.yml 配置代码库

    1
    2
    3
    4
    5
    6
    7
    # Deployment
    ## Docs: https://hexo.io/docs/one-command-deployment
    deploy:
    type: git
    repo: git@github.com:your_github_id/xxxx.github.io.git
    # example, https://github.com/hexojs/hexojs.github.io
    branch: gh-pages
    • 说明: 这里的 url 可以是 http https 也可以是 git url 但是建议使用 git url
    • 实测在 push 文件到 github 时使用 https 路径,经常会有异常抛出,使用 git url 后比较稳定
    • 使用 https url 需要在 url 上添加授权方式和 token 像这样 repository: https://oauth2:your_token@github.com/*****.github.io, 实测可行 on Nov 1 2021
  • 修改 package.json 添加一条生产可发布博文的命令, 默认初始化项目时已经添加了该命令,如果没有则手动添加一下

    1
    2
    3
      "scripts": {
    "build": "hexo generate",
    }
  • 为了防止将一些非必要的文件推送到 github 仓库,创建一个.gitignore 文件, 内容如下:

    1
    2
    3
    4
    5
    6
    7
    .DS_Store
    Thumbs.db
    db.json
    *.log
    node_modules/
    public/
    .deploy*/
  • 创建 gitHub token
    打开自己的 GitHub 主页,点击自己的头像找到 Settings 并进入, 选择 developer settings 在左边目录栏找到 Personal access tokens,点击 Generate new token,按照步骤申请即可,过程比较简单, 这里不详述。Scopes(范围)只需要授权 repo:status 和 repo:public_repo 权限即可 。Token 申请成功后,将 Token 复制并保存起来.当运行发布命令时需要输入此 token 作为密码

  • 安装 hexo-git plugin

    1
    2
    3
    npm install hexo-deployer-git --save
    或者
    cnpm install hexo-deployer-git --save //推荐
  • 这样前期准备工作基本完成,现在开始发布博客
    发布博客系统使用如下命令:

    1
    hexo clean && hexo generate && hexo deploy

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

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

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

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

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

    1
    2
    3
    4
    5
    6
    7
    2021/10/04/post
    archives
    css
    fancybox
    js
    tags/Hexo
    index.html

8. 选择一个漂亮的主题

这里我选择的是 Next 主题, 具体配置可以参考鹏叔的技术博客 - Hexo 配置 Next 主题

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

可以参考我的文章 Hexo 博客添加评论功能

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

10. 文章置顶

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

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

1
2
3
4
---
title: example
sticky: 100
---

11. 参考文档

Hexo 官方文档

Hexo 配置文档

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

12. trouble shooting

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

    具体错误信息如下

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    $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 的文件数上限

    1
    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
  2. 问题: The TLS connection was non-properly

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    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/_hexo-util@2.5.0@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:

    解决办法

    解决办法有三种,
    修改_config.yml 文件的 deploy 部分,将 https 修改为 http url 或者 设置为 git url, 配置为 https oauth2 加 token

    1. 设置为 git url(推荐)
    1
    2
    3
    4
    deploy:
    type: git
    repo: git@github.com:your_github_id/your_github_id.github.io.git
    branch: gh-pages

    这里建议配置为 git url

    1. 将 https 修改为 http url
    1
    2
    3
    4
    deploy:
    type: git
    repo: git@github.com:your_github_id/your_github_id.github.io.git
    branch: gh-pages
    1. 在 repo https url 上要添加授权方式和 token
    1
    2
    3
    4
    deploy:
    type: git
    repo: https://oauth2:your_github_token@github.com/your_github_id/your_github_id.github.io.git
    branch: gh-pages
  3. 问题: 站内链接跳转不灵

  • 现象:

    当时使用 markdown 标准的站内跳转链接写法时,再发布后发现链接是错的跳转不过去,例如

    1
    [如何创建一个 nodejs 模块](how_to_create_a_node_module.md)
  • 原因分析: 生成的链接是不对的,路径上缺少了年月等信息

  • 解决办法

    替换为下面这种写法,就能正确跳转

    1
    {% post_link nodejs/how_to_create_a_node_module %}

    更多详细分析可以参考知乎上的这篇文章

  1. 链接包含中文不能正常跳转问题
  • 现象:当右侧大纲条目中包括中文时,点击不能正确跳转
    打开浏览器开发者模式发现以下错误

    1
    2
    utils.js:240 Uncaught TypeError: Cannot read property 'getBoundingClientRect' of null
    at HTMLAnchorElement.<anonymous> (utils.js:240)
  • 原因分析:

    中文链接在转码后不能正确的映射到相应的页面元素

  • 解决方案

    我已经通过此issue反馈给 hexo 社区,社区的回复是在新的 Next theme 中已经解决此问题,需要升级 next theme 到新版本, 以下是来自社区的回复:

    1
    2
    This issue has been fixed in next-theme/hexo-theme-next@0d2b3af
    Theme NexT version 7.8.0 is outdated. The latest version is v8.8.0 https://github.com/next-theme/hexo-theme-next/releases/tag/v8.8.0

13. 相关阅读

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

Hexo 命令详解

Hexo 博客添加评论功能

Hexo 配置 Next 主题

Hexo 博客搜索引擎优化