本文主要记录我用 HexoGitHub Pages 搭建个人博客的过程,主要包括以下章节:

Hexo

什么是Hexo?

快速、简洁且高效的博客框架

超快速度
支持 Markdown
一键部署
丰富的插件

个人使用下来的感受是:安装、使用简单,部署方便,专注于写作,主要得益于下面几点:

  • 支持Markdown,专注于写作
  • 资源管理方便,如图片支持两种管理模式
  • 学习成本很低,常用的命令不超过5个
  • 灵活的插件,如发布到各个托管网站
  • 漂亮简洁的主题,有相关能力的还可以自己修改主题或者制作主题

Hexo目录结构说明

├── _config.yml 网站的配置信息
├── package.json 应用程序的信息。EJS, Stylus和Markdown renderer已默认安装
├── scaffolds 模版文件夹。当您新建文章时,Hexo会根据scaffold来建立文件
├── source 资源文件夹是存放用户资源的地方
├── ├── _drafts 草稿箱,可以将不想发布的文章放在该目录下面,比如我将自己的写作模板文件放在这里
├── └── _posts 该目录下的文件会被生成和发布
├── themes 主题文件夹。Hexo 会根据主题来生成静态页面
└── public 执行generate命令后生成public文件夹,并解析Markdown和HTML文件到该目录

常用命令

以下是操作Hexo书写、生成、部署博客常用的几个命令,后面会有详细介绍:

  • hexo init [folder]
  • hexo version
  • hexo list <type>
  • hexo new [layout] <title>
  • hexo publish [layout] <filename>
  • hexo generate
  • hexo clean
  • hexo server
  • hexo deploy

Example

创建草稿,写作,本地预览

  • hexo --config custom.yml new draft my_blog
  • hexo --config custom.yml server --draft

写作完成之后,发布草稿,生成静态博客,并部署到 Github Pages

  • hexo --config custom.yml publish draft my_blog
  • hexo clean 正常情况不需要执行该命令
  • hexo --config custom.yml generate
  • hexo --config custom.yml deploy

我的搭建过程

安装Hexo

按照Hexo官网的步骤依次安装即可。

  • Git
  • Node.js
  • Hexo

升级 Hexo 的建议:

  • 小版本内除非必要,否则不要升级,意义不大
  • 大版本升级最好重新创建 Hexo 工程,然后拷贝博客源文件和相关配置
  • 上述建议的原因是我在网上看到了很多升级的惨痛教训

安装主题

官网有很多的主题,每个都有说明文档,照着按照即可,本博客使用的是apollo

下面是我浏览所有主题之后觉得比较好看的,后面的星表示大致的喜欢程度:

PS:若主题是通过 Github 管理的,则可直接进入主题目录通过 git 命令对其更新。

修改配置文件

我主要修改了下面的内容:

  • 博客基本信息:标题、作者等
  • deploy信息:指定部署的网站
  • 主题:选择主题,并修改对应的主题配置文件,比如评论和谷歌分析;

Hexo支持本地自定义配置文件,然后在执行Hexo命令时通过--config字段指定本地配置文件即可,如我本地的配置文件叫做custom.yml,用法如下:

  • hexo --config custom.yml new [layout] <title>
  • hexo --config custom.yml server -p 5000
  • hexo --config custom.yml server -p 5000 --draft

安装插件

可通过插件来扩展Hexo,提升Hexo的写作体检,插件基本有下面两个方面的来源:

  • 模板会内置一些插件
  • 自己安装插件

Disqus评论

我的评论系统选择的是Disqus,个人感觉比多说优势多太多,而且功能强大,唯一的不好就是需要翻墙。

一些Tips:

  • 163邮箱默认收不到Disqus的邮件,需要设置白名单
    • 在邮箱中依此点击:“设置”->“反垃圾/黑白名单”->在白名单中添加disqus.com
  • Migration Tools 很强大,很好用;本质是将旧的Url映射到新的Url,并且支持多个Url映射到同一个新的Url,可用于完成下面功能:
    • 将旧Url的评论迁移到新Url
    • 将多组评论汇总到一个Url
    • 删除Url,通过将其映射到其他Url(一般映射为已存在的Url)即可删除该Url,参考自How can I delete Discussions?

写作

通过 hexo new filename 创建新的文章,用Markdown编辑器完成文章内容的编写。

部署博客

本博客选择部署在 GitHub Pages 上面,具体可参考Hexo部署:Git

关于 GitHub Pages 的介绍可参考官方文档:What is GitHub Pages?

购买并绑定域名

具体方法可Google或者参考文章后面的参考链接:

博客备份

俗话说备份容灾非常重要,博客源文件的备份亦是如此,尤其随着博客数目增加之后,备份既可以保存原始文件用于恢复博客,还能够帮忙对比每次的修改,避免意外误操作已有的博客文件。

常用的备份策略:

  • 在本地磁盘备份博客源文件
  • 通过 Github、Bitbucket 等网络仓库备份,个人建议私有仓库,恰巧 Bitbucket 提供免费的私有仓库,值得拥有

上述两种方案都可以通过手工操作,也可以写代码辅助自己完成;为此我专门写了一个备份程序,辅助自己完成备份,简单方便。

我的备份方案是采用 Bitbucket 的私有仓库,本地采用自动化脚本辅助备份、还原,备份工具及说明可参考我的 Github 仓库:tanchao90/hexo-git-backup

遇到的问题

bash: hexo: command not found

在 Windows 下有两种提示,同一个意思

  • cmd 窗口: ‘hexo’ 不是内部或外部命令,也不是可运行的程序或批处理文件
  • Git Bash窗口: bash: hexo: command not found

我在安装的过程中遇到了该错误,最终是通过卸载 Node.js 和 Git,并重新安装它们和 Hexo 解决的
为此还在 Hexo 项目下面发起了一个Issue:Windows 7: bash: hexo: command not found #1871

npm WARN optional dep failed, continuing fsevents@1.0.11

这是我安装 Hexo 时出现的警告,通过 Google 发现是

fsevents is an API available only on OSX

npm WARN optional dep failed, continuing fsevents@0.3.6

可以忽略该警告,至少我没遇到什么问题

博客乱码问题

最近迁移旧博客到 Hexo 时遇到神奇的乱码问题,包括本文扩充之后也出现了,坑了我很久,还以为是特殊代码片段引起的解析问题,具体估计是下面的原因导致的:

实测表明:该问题只在本地Server调试时存在,上传到GitHub Pages之后正常显示;
个人猜测可能是本地每篇文章的缓存空间不足导致。

ERROR Deployer not found: git

在2017年2月份的时候,尝试重建了一次 Hexo 环境,结果遇到了上述错误,最终参考 升级hexo碰到“Deployer not found”问题及解决 解决,解决办法是执行下面的命令安装 git 组件:

npm install --save hexo-deployer-git

命令详细说明

这部分内容可以直接查看官网,那里的信息最新最准确。

init: 新建一个网站

$ hexo init [folder]

version: 显示Hexo版本

$ hexo version

new: 新建一篇文章

hexo new [layout] title
layout指定文章的布局,默认为 post,可以通过修改_config.yml中的default_layout参数来指定默认布局
Hexo 有三种默认布局:post、page 和 draft,它们分别对应不同的路径,而您自定义的其他布局和 post 相同,都将储存到 source/_posts 文件夹

post source/_posts
page source
draft source/_drafts

generate: 生成静态文件

$ hexo generate
-d, –deploy, 文件生成后立即部署网站
-w, –watch, 监视文件变动

clean: 清除缓存文件(db.json) 和已生成的静态文件 (public)

$ hexo clean

list: 列出网站资料

$ hexo list type

publish: 发布草稿,也就是将source/_drafts中的草稿文件移动到source/_posts文件夹

$ hexo publish [layout] filename

server: 启动服务器,默认访问网址为http://localhost:4000/

$ hexo server
-i, –ip, 重设ip,覆盖默认的0.0.0.0
-p, –port, 重设端口
-s, –static, 只使用静态文件,也就是不监听文件变化
-l, –log, 启动日记记录,使用覆盖记录格式

deploy: 部署网站

$ hexo deploy
-g, –generate, 部署之前预先生成静态文件

若部署到Git(Github),需提前安装hexo-deployer-gitnpm install hexo-deployer-git --save

render: 渲染文件

$ hexo render file1 [file2] …
-o, –output, 设置输出路径

选项: 在执行上面的命令时还可以增加下面的选项,完成额外功能

$ hexo –safe 安全模式,在安全模式下,不会载入插件和脚本
$ hexo –debug 调试模式,在终端中显示调试信息并记录到 debug.log
$ hexo –silent 简洁模式,隐藏终端信息
$ hexo –config custom.yml 自定义配置文件的路径,执行后将不再使用 _config.yml

官方文档梳理

梳理 Hexo官方文档,帮助自己回忆每个模块的内容,读者可以直接查看官网。

基本操作

  • 写作: 主要介绍一般的写作流程,从创建文章到发布
  • Front-matter: 可以方便的修改文章信息,如指定文章建立时间,对发布历史文章非常方便~(≧▽≦)/~
  • 标签插件(Tag Plugins): 支持多种标签格式,如引用文章内容、代码块、图片等,这一节功能强大,能极大的帮助丰富文章内容
  • 资源文件夹: 主要讲了Hexo中图片等资源的管理,普通用户将资源放在source目录下即可
  • 数据文件夹: 实现数据复用
  • 服务器: 详解server命令
  • 生成器: 详解generate命令
  • 部署: 讲解deploy命令和相关配置,可以部署到GitHub、Heroku等,详细说明了每一种对应的配置

自定义

  • 永久链接(Permalinks):配置网页链接的格式
  • 主题:添加、配置主题,主题目录说明
  • 模板:模板的使用
  • 变量:Hexo支持的变量,可在模板中使用
  • 辅助函数:列举了Hexo内置的所有函数
  • 国际化(i18n):国际化的配置,也就是支持多语种选择
  • 插件: 插件使用和开发

参考文章