Hexo+Github搭建博客详细笔记

前言

📰博客——可能这个东西在大多数眼中已经落后于时代甚至压根没听过。在这个信息碎片化、人人信息获取不对等的时代，各个社交平台可以很快速地发送动态、短视频，方便的跟自己的朋友们点赞、互动，而花大量时间金钱和精力去维护一个没人看的博客未免显得有点蠢？

👨‍🔧对于个人来讲，拥有自己的域名、自己的博客、能庞大的互联网拥有自己的清静的一亩三分地，留下自己的所见所得、所想所思、能够和一同坚持维护自己的博客的人一起交流、交朋友（互换友链）……这都是很有很有意义的事！

写博客的人应该都会经历三个阶段：（个人偏主观总结😜）

• 第一阶段：接触WordPress等大型博客程序，尝试各种复杂的功能，乐于折腾各种花里胡哨的
• 第二阶段：使用Markdown进行创作，追求更加轻量简洁的程序，比如Typecho、Z-Blog、Emlog……
• 第三阶段：希望能够脱离服务器，降低博客维护成本，更加专心于写作而不必花费大量时间在服务器维护上，但同时又希望自己拥有博客的完整掌控权，又有了Hexo、Hugo、Gridea等静态博客程序

第三阶段很多人就是从动态博客程序转到静态博客程序，使用Github、Gitee、Coding、Gitlab…等Git代码托管仓库的Pages功能托管自己的静态博客🏃‍♀️

本篇文章全部自己码字、截图，未经本人授权许可，谢绝转载和二次创作！

初识Hexo

静态博客程序有很多，还有很多大佬甚至自己写静态博客生成器，常见的有Hexo、Hugo、Jekyll等等，这里介绍的是Hexo的一些搭建记录。为什么使用Hexo和Github Pages？Hexo基于Node.js静态博客框架，拥有庞大的社区/开源支持，仅需要极少的依赖、拥有超级丰富的主题和插件，支持Markdown语法；而Github Pages免费、基于Git的版本控制不用担心文章丢失、博客生成的静态文件存储在Github仓库不用担心丢失（删除跑路除外🙄）

Hexo基于Node.js的静态博客框架，通过把Markdown格式的文章渲染成静态Html网页，通过Git进行文章的发布、更改，可以部署到任意的Git平台（Github、Gitlab、Coding、Gitee…）以及自己的服务器/VPS；本文以Windows系统下部署到github为例，在开始前我们需要：

• 安装Node.js（推荐LTS版）

  请注意，目前对于Hexo在Nodejs >= 14版本上在运行时有很烦的输出，虽然不影响使用，建议使用低于14版本的LTS版！

  

• 安装Git

  

上面的两个都以默认设置安装就行，如果你需要更改安装路径可能需要自己配置环境变量，这个请自行百度

在安装完Git和Node.js后在任意文件夹右键打开Git bash here即可打开Git的Bash终端

在Git终端里分别输入下面命令并回车，查看Git和NPM版本号：

$ git --version
$ NPM -v

如果你的配置没问题，应该是类似于下图这样的：

安装Hexo

Hexo全局安装有两种方式：

• NPM安装
• Yarn安装

对于新手，本文建议直接使用NPM安装，但是随着使用Hexo的时间变长，我个人更推荐使用Yarn安装，Yarn安装的教程请看后面

NPM全局安装Hexo

✅在完成上面的Git和Node.js的正确安装后你就可以在本地安装Hexo了，😉以下命令均在Git Bash里面进行，使用NPM安装Hexo，输入命令：

$ npm install -g hexo-cli 

📌这个安装时间视你的网速而定，由于在国内的部分地区或者运营商因为DNS污染或者防火墙导致Git或者NPM很慢，🚀请看这篇：给 Git 和 NPM 代理加速

Yarn全局安装Hexo

下面以Windows为例在Yarn中文文档里向我们提供了三种安装Yarn的方式：（这三种方式都得需要安装有Node.js）

Node.js版本支持： ^4.8.0 || ^5.7.0 || ^6.2.2 || >=8.0.0

• 使用Windows安装程序：https://classic.yarnpkg.com/latest.msi

  这提供的是标准的Windows Installer 程序包 (.msi)，只需要下载、安装过程会自动添加Yarn到系统的环境变量，这也是较为推荐的安装方式

• 通过Chocolatey安装

  Chocolatey是Windows下一个软件包包管理工具，按照Chocolatey官方文档安装好Chocolatey后，你只需要一行命令即可安装Yarn：

  choco install yarn

• 通过Scoop安装

  Scoop是Windows下的一个基于命令行的软件包管理工具，安装好Scoop后：

  scoop install yarn

PS：请将您的项目目录和 Yarn 的缓存目录 %LocalAppData%\Yarn 列入杀毒软件的白名单中，否则会因为每次向磁盘写入文件时而被扫描，导致安装软件包变得很慢。

虽然yarn还可以通过npm安装（npm install yarn），但是yarn文档不推荐这样做，所以本文建议从上面三种方法三选一！

检查Yarn是否安装成功：

$ yarn --version

安装好Yarn后，全局安装Hexo也仅需要一条命令：

$ yarn global add hexo-cli

初始化Hexo

🎈在你想要存储Hexo本地源文件的目录打开Git Bash，然后初始化Hexo，比如我想要在D盘的一个名为hexo的文件夹进行写作，那我在D盘打开Git Bash使用下面的命令初始化Hexo博客：

$ hexo init hexo

此时就会自动新建一个名为hexo的文件夹，并且hexo已经在该文件夹内完成初始化，一般的打开这个目录的结构是下面这样的（注意其中.deploy.git需要在本文后面配置完Github和本地连接才有哦）

一般的，hexo内目录基本结构如下：

.
├── _config.yml # Hexo的全局配置文件，在此配置网站的主要参数
├── package.json # npm软件包以及版本信息
├── scaffolds # 模版文件夹
├── source  # 资源文件夹
|   ├── _drafts # 草稿/模板文件
|   └── _posts # 文章（每篇文章使用markdown格式写好保存在这里）
└── themes  # 主题文件夹

安装依赖

• 如果你是使用NPM的，在bash下使用NPM安装hexo必须的依赖：

  $ npm install

• 如果你是使用Yarn的，在bash下使用yarn安装hexo必须的依赖：

  $ yarn install
  或者
  $ yarn

Hexo的基本命令

$ hexo clean #清除生成的博客静态文件
$ hexo g #生成博客静态文件=命令hexo generate
$ hexo s #启动博客的本地预览=命令hexo server
$ hexo d #推送博客到远程仓库=命令hexo deploy
$ hexo new page xxx #新建名为"xxx"的页面
$ hexo new xxx #新建名为"xxx"的文章
$ hexo d -g #生成静态博客并推送到Git远程仓库
$ hexo s -g #生成静态博客并启动本地预览

本地预览

上面几部完成，你就可以输入下面命令启动本地预览hexo博客了：

$ hexo s

回车后打开浏览器，输入http://localhost:4000就可以预览你的博客了

如果上面hexo s没有成功，可能是本地的4000端口被占用，请使用hexo s -p 端口号的方式修改本地预览的端口号，然后打开浏览器，输入http://localhost:你的端口号来启动本地预览😉

✅至此，你的Hexo博客已经安装完成，下面说明关联Github仓库并推送至Github Pages

关联Github仓库

创建仓库

• 登陆（没有就注册一个）你的Github账号

• 新建一个名为username.github.io的Public仓库，其中username是你的Github用户名，比如我的用户名是Spoience，那么我新建的仓库名称即为：Spoience.github.io

  

• Description是仓库描述，自己随便写即可

• 勾选Initialize this repository with a README，点击Create Repository完成仓库的创建

• 点击仓库的Settings勾选Github Pages

链接Git到远程仓库

📌打开本地Git Bash，分别输入以下命令：

$ git config --global user.name "username" # username是你的Github用户名，注意大小写保持一致
$ git config --global user.email "your email address" # your email address填写你的Github注册用的邮箱
$ ssh-keygen -t rsa -C "your email address"  # 生成SSH公钥，your email address同上填

完成上面步骤后默认生成的密钥在C:\Users\用户名\.ssh\目录下，以文本编辑器打开id_rsa.pub文件，复制里面的所有内容，后面会用到

• 在Github点开自己头像打开Settings页面

  

• 选择SSH and GPG Keys，点击New SSH Key

  

• Title随便填，自己能辨识就行了，Key中粘贴上面你在本地id_rsa.pub文件中复制的所有内容，点击Add SSH Key

• 打开Git Bash，输入下面命令:

  $ ssh -T git@github.com

  就会出现，类似图中的提示：(Hi 用户名! You’ve successfully authenticated，but……)

  

• 打开hexo目录下的_config.yml文件，修改最后一行的deploy配置信息：

  deploy:
    type: git
    repo:
      github: https://github.com/username/username.github.io.git # Git仓库地址，username是Github用户名
    branch: master # 部署到仓库的master(主)分支

在此请注意：

从UTC时间2020年10月1日起，github创建仓库的默认主分支由master改为main，在此之前已经创建的仓库保持master主分支不受影响，如果你是在此（UTC 2020.10.1）之后时间创建GitHub仓库并且尝试使用github托管你的Hexo站点，请将上面branch后面的master改为main（与你仓库实际保持一致就可以了）

安装Hexo推送Git插件

在hexo根目录打开Git Bash，安装Hexo推送Git插件：

• 对于NPM安装的Hexo

$ npm install hexo-deployer-git --save

• 对于Yarn安装的Hexo

$ yarn add hexo-deployer-git

测试推送到远程仓库

$ hexo clean # 清除生成的静态文件
$ hexo g # 生成新的博客静态文件
$ hexo s # 启动本地预览
$ hexo d # 推送博客静态文件到远程仓库

如果每次hexo deploy都要输入github账号密码登录，bash下执行：

$ git config --global credential.helper store

🚩如果前面没有出错的话，再次执行上面命令，你发现hexo d后本地预览的博客已经推送到你的远程仓库了，并且浏览器地址输入username.github.io可以访问你的博客了，代表推送博客静态文件到Github成功了！

进阶配置

🎈上面的配置成功表示你的Hexo写作环境已经完成，下面是一些个性化以及站点信息的配置

[推荐]关联自定义域名

username.github.io是github pages的二级域名，他是免费提供的，如果你想要更个性化，推荐使用自己的域名

• 打开你博客仓库的Settings，找到Github Pages栏填入你自己的域名，比如我的是：spoience.com

• 进入自己的域名控制台，添加一条CNAME记录，记录值是你的博客的仓库名，比如我的：

  

• 强制全站SSL

  稍等一会儿，待域名的解析记录生效后，打开博客仓库的Settings，推荐勾选Enforce HTTPS，Github会帮你申请免费的SSL证书（来自Let’s Encrypt），至此博客的HTTPS设置完成

  

  Github默认的是使用Let’s Encrypt Authority X3的SSL证书，有效期三个月，到期会自动续签，主流现代浏览器都兼容

  

✅之后你就可以通过自己的域名访问自己的博客了

修改主题

Hexo拥有非常丰富的主题,其中99%都是开源的免费主题，本站使用的是Butterfly主题，以该主题为例，Clone主题：

$ git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

修改Hexo的配置文件_config.yml:

theme: landscape # 默认的主题
# 修改为你的主题名，比如：butterfly
theme: butterfly

📌各种主题的进阶配置以及详细说明请看该主题作者写的文档

尽管没有任何硬性限制这些不尊重版权信息和开源精神的人假如您搭建了Hexo博客，使用了开源的主题，希望您也能尊重开源精神，不要随意修改或者删除Hexo和Hexo主题的版权信息，如果您有空的话可以给这些项目点个Star，这是对开源项目维护者力所能及的支持（本站不与任何删除主题版权的博客交换链接！）

修改站点信息

您可以在hexo的 _config.yml 中修改大部分的站点配置,Hexo的配置文件使用YAML语法，请注意空格和字符缩进

参数	描述
title	网站标题
subtitle	网站副标题
description	网站描述
keywords	网站的关键词，使用半角逗号 , 分隔多个关键词
author	网站作者名称
language	网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考你的主题的文档自行设置，常见的有 zh-Hans和 zh-CN。
timezone	网站时区，一般的，对于中国大陆地区可以使用 Asia/Shanghai

推荐插件

插件名称[点击链接访问]	插件描述
hexo-abbrlink	优化/自定义Hexo永久链接格式
hexo-generator-feed	生成RSS、Atom订阅链接
hexo-filter-nofollow	将nofollow属性自动添加到所有外部链接
hexo-generator-sitemap	生成xml格式的站点地图
hexo-generator-baidu-sitemap	专门生成百度可识别的站点地图
hexo-wordcount	给文章添加字数统计
…	…

升级Hexo

一般的，我们可以直接使用npm-check-updates来升级Hexo已经安装的npm包为最新版本，在Hexo本地的根目录打开Bash终端

对于使用NPM安装/管理的Hexo，按照以下步骤升级：

# 查看hexo版本信息
$ hexo -v
# 全局升级 hexo-cli
$ npm install hexo-cli -g
# 检查升级
$ npm install -g npm-check
$ npm-check
# 开始升级
$ npm install -g npm-check-updates
$ npm-upgrade
# 更新全局依赖
$ npm update -g
$ npm update --save

对于Yarn安装/管理的Hexo，按照以下步骤升级：

# 查看hexo版本
$ hexo -v
# 全局升级hexo-cli
$ yarn global add hexo-cli
# yarn添加 npm-check-updates
$ yarn global add npm-check-updates
# 升级全部依赖，yarn.lock和package.json也会被更新
$ ncu --upgrade --upgrade All
# 全局更新
$ yarn upgrade --latest
# 安装依赖
$ yarn install
# 或者只需要一步代替上面yarn更新hexo步骤（忽略package.json指定的版本范围所有的都将被升级到最新版）
$ yarn upgrade-interactive --latest

Hexo之禅

• 折腾主题是Hexo的最大原罪。专注于创作，而不是令人眼花缭乱的效果。名家之博，不假于主题之花哨，而得知于内容；
• 样式千万种，花哨莫去求。主题若彩虹，遇上方知有；
• 有问题记得首先去查看官方文档，善用搜索引擎。没有人有义务的无条件帮你；
• 善于分享，赠人玫瑰手有余香。写作是检索你对知识理解程度的手段，而分享是你继续创作的动力；
• 不忘初心，方得始终。

结语

🌼基本把Hexo开始的全部步骤都介绍了，希望纯小白也能看懂🙄，除了上面的配置之外更多的关于主题的配置你可以看主题作者写的文档，一般文档都比较详细，得益于庞大的用户群体和社区支持，绝大多数问题你都可以通过Google搜索和阅读Hexo文档或者主题文档找到解决方法。如果你在使用中遇到一些无法理解、无法解决的问题也希望你在了解提问的智慧后在开源社区进行提问，所有人的时间都很宝贵，熟读提问的智慧可以一定程度上让你少走弯路🚀

🎈最后，Hexo博客搭建完的一些进阶步骤/优化，希望对你有所帮助：

• 👨‍🔧优化Hexo文章的永久链接
• 🍰Valine Admin食用指南
• 📌Hexo官方文档
• 🎈提问的智慧
• 🚀使用本地代理加速Git和NPM
• 🏆Markdown写作指北

积分&鸣谢

在写本文之前，Spoience最开始也是个小白，并且在过程中踩了不少坑，但是越使用越喜欢Hexo这个博客框架，在我对Hexo了解甚少的阶段很多热心的大佬给予了我很大的帮助，因此我尽可能的一直在完善、丰富本文的内容，希望能给Hexo入门一点小小的启发或者帮助，如有问题也欢迎指正，如需转载还请手下留情保留版权信息和原文链接，在此万分感谢！

• Hexo Official Docs
• Yarn中文文档
• 睿先森-记Hexo版本升级和插件升级
• Web前端开发小K-hexo常用命令
• Yarn Official Docs——yarn upgrade