Hexo+GitHub搭建个人博客教程

type

status

date

slug

summary

一、环境配置

在搭建之前电脑需要的环境配置如下：

node.js

我们可以在控制台中输入

如果没有报错则说明 git 和 node.js 已经安装成功，可直接跳过安装教程，如果报错则需要重新安装

1、安装git

windows 用户：直接下载 git安装程序根据提示进行安装

mac 用户：通过 homebrew 进行安装，没有安装的需要先安装 homebrew，可以通过命令 $ brew install git 安装，也可通过下载 git安装程序进行安装

linux 用户：通过命令行安装 $ sudo apt-get install git-core

安装完成后再在控制台输入

如果没有报错则说明安装成功

2、安装node.js

下载安装程序（推荐）

直接下载 node.js安装程序进行安装，比较快捷省事，适用于 mac 和 windows 用户

使用nvm安装

cURL:

Wget:

安装完成后，重启终端并执行下列命令即可安装 Node.js。

安装完成后再在控制台输入 $ node -v 如果没有报错则说明安装成功

3、github pages

我们用来托管博客的服务叫做 Github Pages，它是 Github 用来提供给个人/组织或者项目的网页服务，只需要部署到你的 Github Repository，推送代码，便可以实时呈现。GitHub Pages 有两种类型：User/Organization Pages 和 Project Pages，两者的区别是：

User Pages 是用来展示用户的，而 Project Pages 是用来展示项目的。

用于存放 User Pages 的仓库必须使用 username.github.io 的命名规则，而 Project Pages 则没有特殊的要求。

User Pages 将使用仓库的 master 分支，而 Project Pages 将使用 gh-pages 分支。

User Pages 通过 http(s)://username.github.io 进行访问，而 Projects Pages 通过 http(s)://username.github.io/projectname 进行访问。

申请github账号

首先你需要申请注册一个 github 账号

创建托管仓库

点击右上角 New Repository 新建一个仓库来作为托管仓库，注意命名为 username.github.io（username是你的账号名)。一般搭建个人博客都是用 User Pages，所以命名需要按照规范命名。

配置SSH（可跳过）

SSH实现本地 git 项目和远程 github 的连接，github 通过 SSH 密钥识别特定的可信任电脑，该部分电脑在向 github 推送的时候不需要输入用户名和密码

查看电脑是否已经配置 ssh key

默认情况下，public keys的文件名是以下的格式之一：id_dsa.pub、id_ecdsa.pub、id_ed25519.pub、id_rsa.pub。因此，如果列出的文件有public和private钥匙对（例如id_ras.pub和id_rsa），证明已存在SSH keys。如果提示 No such file or directory 则说明未安装

第一次安装完 git 需要先 初始化配置 git（可跳过）

生成新的 SSH Key，输入密码之类的可以省略，一路回车就行

复制执行命令后显示的 key 内容

点击右上角的 Settings –> SSH and GPG keys –> New SSH key ，Title 自由填写，Key 粘贴刚才复制的那段代码，点击 Add SSH Key

测试连接

如果看到

输入yes，回车看到

表示连接成功，ssh的配置至此完成。

二、安装启动Hexo

1、下载Hexo

有些教程会用命令 $ npm install -g hexo，作用同上，均为下载Hexo的安装包

2、初始化Hexo

执行下面命令把 folder 作为 Hexo 初始化安装目录。

如果以上的安装成功，在安装目录 folder 下将会出现以下的文件结构

_config.yml：网站的全局配置文件

package.json：应用程序的信息

scaffolds：模版文件夹，Hexo的模板是指在新建的markdown文件中默认填充的内容。当您新建文章时，Hexo 会根据 scaffold 来建立文件。例如，如果您修改 scaffold/post.md中的Front-matter 内容，那么每次新建一篇文章时都会包含这个修改。

source：资源文件夹，除 _posts 文件夹之外，开头命名为 _ (下划线)的文件 / 文件夹和隐藏的文件将会被忽略。Markdown 和 HTML 文件会被解析并放到 public 文件夹，而其他文件会被拷贝过去。例如用于域名解析的 CNAME 文件就可以放到该文件夹中，每次部署的时候都会自动添加该文件。

themes：主题文件夹，Hexo 会根据主题来生成静态页面。

3、启动

进入hexo的安装目录，输入命令

进行启动，可简化为 $ hexo s ，也可启动调试模式 $ hexo server --debug

启动完成后访问地址：http://localhost:4000/

三、编写文章

1、创建文章

执行以下命令可新建文章。

layout 叫做布局，不同的 layout 选项会创建不同类型的文章。hexo有三种默认布局，用户也可以自定义布局，不同布局对应不同的存储路径

post：一般文章布局，自定义布局和post的对应的存储路径为 source/_posts

page：页面布局，例如可以用于生成标签（tags）或分类（categories）等主页面，就是点击菜单直接显示的页面，对应的存储路径为 source

draft：草稿布局，草稿默认不会显示在页面上，已完成的草稿可用 $ hexo publish <title> 来发布，对应的存储路径为 source/_drafts

Hexo 默认以标题做为文件名称，可以修改_config.yml的 new_post_name 参数来修改新生成的文件名称，例如

文件名会带上年月日，:title 表示转为小写，空格将会被替换为短杠。

例如使用下面命令创建新文章。

source/_posts 下面会自动生成一个名为 2019-08-02-hello-world.md 文件。

2、编辑文章

文章内容分为前页和正文。文章头部 — 分隔符上方是前页，下面是正文。

前页

可以设置的变量有：

layout：布局

title：标题

date：建立日期，默认为文件建立日期

updated：更新日期，默认为文件更新日期

comments：开启文章的评论功能，默认为true

tags：标签，不适用于布局为 page 的的页面

categories：分类，不适用于布局为 page 的的页面

permalink：覆盖文章网址

categories 和 tags 的区别：categories 具有顺序性和层次性，tags 没有顺序和层次。例如下面 Life 成为 Diary 的子类。在界面上显示就是 Diary/Life。
categories:
Dairy
Life

例如创建一篇文章题目为 hello-world，文章创建时间是 2018-06-10 16:15:04，分类归为 Diary 的子分类 Life，贴上 happy 和 friend 两个标签，最后禁止评论。

正文

正文和普通的 markdown 编辑相同。首页默认会显示全部文章的全部内容，很多情况下我们只想在首页显示每篇文章的序言等部分内容，这样有利于读者总览。我们只需要在文章添加一句  ，例如

 以上的内容1会在首页正常显示，以下的内容2会隐藏，并显示 阅读全文 等链接。

四、部署

1、部署前配置

我们在本地编辑的文章只能在本地查看，如果想把文章发布到网上，我们需要把文章上传到上面配置好的 github pages 中。在发布文章前我们需要进行一些配置。

安装deployer工具

hexo-deployer-git 为 hexo 自动部署安装工具，可通过命令安装

配置_config.yml文件（旧版）

编辑安装目录下的 _config.yml 文件，找到 deploy 参数，把 type 改成 git，repo 改成你自己的仓库地址，该地址可以直接上 github 上获取。注意type: 和 git之间必须带一个空格。

注意 github 从2021年8月13日开始不在支持通过输入账号密码的形式 push 代码，在使用账号密码 push 代码时，会提示如下错误：

现在需要使用 personal access token 个人访问令牌，所以要使用下面新的配置步骤。

获取 access token

Settings ——Developer Settings——Tokens，点击 Generate new token。

在 Note 中填入这个 token 的具体用途（随便填方便记忆即可）

在 Expiration 中选择 token 的有效时间默认30天。

在 Select scopes 中设置该 token 的权限，这里我只是需要 push 下代码所以只勾选了 repo，你可以根据自己的需求进行设置。

点击最下方的 Generate token 按钮即可生成。

生成 token 之后，注意要把 token 保存下来，页面关闭之后不能再查看 token。而且这个 token 的权限很高，不要直接公布在公网上。

把 access token 添加到环境变量

以 mac 为例，这里的 access token 就是上面生成的。

配置_config.yml文件

2、部署

清空

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

生成静态文件

生成 public 静态文件夹

部署

部署到 github 上面

执行完以上命令后，在浏览器输入 https://username.github.io 就可以浏览你的刚才发布的博客，至此 Hexo + Github 的个人博客搭建已经完成。

五、Hexo常用命令

上述 command 可指定模式运行，有三种模式：

安全模式。在安全模式下，不会载入插件和脚本。当您在安装新插件遭遇问题时，可以尝试以安全模式重新执行。

调试模式。在终端中显示调试信息并记录到 debug.log。

简洁模式

例如以调试模式启动服务器：

为了快速执行命令，我们可以修改 hexo 根目录下的package.json文件，增加

在 hexo 根目录下执行 npm run <script>，例如部署到服务器：

参考链接

Hexo官方中文文档

HEXO搭建个人博客

搭建个人博客-hexo+github详细完整步骤

如何搭建一个独立博客——简明Github Pages与Hexo教程

GitHub Pages + Hexo搭建博客

使用Hexo搭建个人静态博客