教程：使用Github和Hexo搭建个人博客

前言

在这篇博客里，我详细记录了自己使用 Github + Hexo 搭建个人博客的全过程，以及自己遇到的问题的解决方案，希望可以帮到正在阅读该博文的你。😀

如果你有任何问题，欢迎在留言板里写下你的问题。

开始之前

在开始搭建博客之前，请先确认你是否完成了以下的准备工作：

拥有Github账号；
安装了node.js、npm;
安装了git (git for macOS/Windows/Linux/Unix);

1. Github

进入Github官网注册，请记住你注册时使用的账号和邮箱。

2. node.js & npm

进入Node官网下载与你正在使用的操作系统相对应的版本，并安装。安装成功后，打开 terminal(macOS/Linux)、CMD/Powershell(Windows)等, 输入以下命令检查是否安装成功。

1 2	$ node --version # 查看node版本号 $ npm --version # 查看npm版本号

❗ 如果是Windows系统，请务必将路径正确添加到 PATH 环境变量中。

3. Git

进入Git官网下载、安装最新版本的Git。

如果你对安装Git感到不安，可以参考下面的链接。

Linux: Link
maxOS: Link
Windows：Link

PS: 如果你使用Windows系统，强烈建议你安装 Windows Terminal , 安装方法可以参考上述Windows链接的Part C.

在终端输入 git --version 检查是否安装成功。

可选操作(非必须)：

在终端输入如下命令来设置用户名和邮箱。

1
2
3

$ git config --global user.name "user_name" # user_name填入GitHub用户名

$ git config --global user.email "user_email" # user_email填入GitHub注册的邮箱

查看已设置的用户名和邮箱：

1
2
3

$ git config user.name

$ git config user.email

搭建Github博客

1. 创建仓库

登录Github，新创建一个仓库。仓库名为：username.github.io ，其他的为默认选项即可。

❗ 一定是username而不是name。

2. 配置SSH key

打开 terminal/Git Bash等, 输入以下命令：

1	$ ssh-keygen -t rsa -C "user.email" # user.email为GitHub上注册的邮箱

默认不需要设置密码，连续按回车键即可。结束后，打开用户主目录查看是否成功生成了ssh-key。

用户主目录所在位置：

- macOS/Linux: ~/.ssh
- Windows: C:\Users\<XX>

进入 .ssh 文件夹，你会看到上述操作为我们生成了一个key，包括一个名为 id_rsa.pub 的公钥，和一个名为 id_rsa 的私钥。(⚠️注意：私钥绝不可以泄露，而公钥可以放心告诉别人。)

打开SSH and GPG keys，点击 new SSH Key ，你将会看到如下窗口：

其中 Title 为标题，可以随意填写。将刚才生成的公钥 id_rsa.pub 中的内容复制到Key窗口中，最后点击 Add SSH key。

在终端输入如下命令以检查Github公钥设置是否成功：

1	$ ssh -T git@github.com

1
2
3

# 如果你看到类似如下的信息，则说明设置成功。

Hi XXX! You've successfully authenticated, but GitHub does not provide shell access.

补充：关于配置SSH的用途，可以参考这篇文章

使用Hexo博客框架

1. 什么是Hexo

Hexo 是一个简单、快速、强大的基于 Github Pages 的博客框架，支持 Markdown 格式，有众多优秀插件和主题。

链接：官方文档

2. 为什么要用Hexo

由于 Github Pages 存放的都是静态文件，博客存放的不只是文章内容，还有文章列表、分类、标签、翻页等动态内容，假如每次写完一篇文章都要手动更新博文目录和相关链接信息，相信谁都会疯掉，所以 Hexo 所做的就是将这些 .md 文件都放在本地，每次写完文章后调用写好的命令来批量完成相关页面的生成，然后再将有改动的页面提交到 GitHub 。

3. 安装与配置

说明：我使用的是Windows操作系统，所有的命令我都是在 Windows Terminal 中的 bash shell 中完成的，没有遇到任何问题。

根据网上的经验，如果你使用 git bash , 那么在hexo初始化的过程中你可能会遇到 node_modules 文件夹无法生成的问题，可以配合 cmd 解决该问题(后面会说明)。

1. 安装与初始化

输入以下命令：

1	$ npm install -g hexo-cli # 该命令完成hexo的安装

安装完成后，请根据个人喜好在计算机内创建一个空文件夹（不限制名称），用于存放博客内的所有内容和素材。

使用命令行进入刚才创建的文件夹内，输入如下命令：

1	$ hexo init # 该命令完成hexo在本地博客目录的初始化

完成后请检查文件夹内的内容，如下图：

如果你使用的是 git bash ，并且遇到了 node_modules 文件夹无法生成的问题，可以参考以下解决方案。

❗ 注意：因为我并没有遇到这个问题，所以无法保证该解决方案一定有效。仅供参考。

产生该问题的原因为，在自己的博客文件夹中 .gitignore 文件中添加了 node_modules/ ，导致更新的时候，这个文件夹被忽略，没有被更新上去。

解决方案：

cmd进入博客当前文件夹路径
执行 npm install
执行 hexo server

2. 生成静态文件

在终端输入命令：

1	$ hexo g # 生成静态文件

执行以上命令之后，Hexo 就会在 public 文件夹生成相关 HTML 文件，这些文件在之后会被提交到 GitHub 上 username.github.io 的仓库中。

3. 本地预览

输入以下命令：

1	$ hexo s # 开启本地预览

本地预览服务开启后，打开浏览器访问 http://localhost:4000 或直接点击终端的链接即可。你应该可以看到如下的页面：

通过本地预览，你可以实时查看博客的编辑情况，等博客完成后再部署到 GitHub 上。

4. 上传到Github

1. 配置站点配置文件

hexo 有2种 _config.yml 文件，一个是根目录下的全局的 _config.yml ,在博客文件夹的根目录下；另一个是各个主题 theme 下的 _config.yml 。前者被称为站点配置文件，后者被称为主题配置文件。

打开(推荐用 VS Code )根目录下站点配置文件 _config.yml ，配置有关 deploy 的部分：

2. 安装部署插件

在终端输入以下命令：

1	$ npm install hexo-deployer-git --save # 安装部署插件

如果不进行上述操作，直接使用 hexo d 部署到 GitHub，将会报错。

3. 部署到 GitHub

输入以下命令：

$ hexo d

PS: 对于Windows用户，不要在 cmd 中输入该命令。请使用 git bash or bash shell ，否则会提示 Permission denied (publickey) 。

部署成功后，在浏览器输入 https://<username>.github.io/ ，如果出现下图，则表示部署成功。

到此，我们就完成了博客的搭建工作，剩下的就是学习如何写博客，如何增添你想要的功能，以及如何美化博客。你可以自由探索，也可以参考我使用的方案。

Hexo博客故障记录及美化方案（持续更新）

Hexo常用命令

hexo new “postName” # 新建文章
hexo clean # 清除缓存
hexo generate # 生成静态页面至 public 目录
hexo server # 开启预览访问端口（默认端口 4000，’ctrl + c’关闭 server）
hexo deploy # 部署到 GitHub
hexo help # 查看帮助
hexo version # 查看 Hexo 的版本
hexo s -g # 生成并本地预览
hexo d -g # 生成并上传

PS: Hexo支持缩写命令，即： - hexo n == hexo new - hexo g == hexo generate - hexo s == hexo server - hexo d == hexo deploy

更改主题

如果你不想使用默认主题，你可以自由探索其他的Hexo主题。

官方主题知乎 Github

这里以NexT(Doc) 主题为例，说明一下更改主题的方法。

下载主题：

# 在终端窗口下，定位到 Hexo 站点目录下。使用 Git checkout 代码：

$ cd your-hexo-site
$ git clone https://github.com/iissnan/hexo-theme-next themes/next

启用主题：

与所有 Hexo 主题启用的模式一样。当克隆/下载完成后，打开站点配置文件(根目录下的 _config.yml)，找到 theme 字段，并将其值更改为 next。

到此，NexT 主题安装完成。下一步我们将验证主题是否正确启用。在切换主题之后、验证之前，我们最好使用 hexo clean 来清除 Hexo 的缓存。首先启动 Hexo 本地站点，并开启调试模式（即加上 --debug），整个命令是 hexo s --debug。在服务启动的过程，注意观察命令行输出是否有任何异常信息，如果你碰到问题，这些信息将帮助他人更好的定位错误。当命令行输出中提示出：

INFO Hexo is running at http://0.0.0.0:4000/. Press Ctrl+C to stop.

此时即可使用浏览器访问 http://localhost:4000，检查站点是否正确运行。当你看到站点的外观与下图所示类似时即说明你已成功安装 NexT 主题。这是 NexT 默认的 Scheme —— Muse。

TroubleShooting: 执行 hexo s 时，location:4000显示不对的故障

NexT主题有4中Scheme。如果你想要更换Scheme，打开主题配置文件(theme 文件夹 -> NexT文件夹 -> _config.yml), 修改Scheme：

配置站点信息

打开根目录下站点配置文件 _config.yml ，你可以设置站点的一些基本信息：

title：网站标题
subtitle：网站副标题
description：网站描述
keywords：关键字
author：作者
language：网站使用的语言（注意：一定要设置为主体能够识别的语言，否则会出现乱码）
- 你可以在 "" 中找到主题支持的语言
timezone：网站时区。Hexo 默认使用您电脑的时区

创建博文

🦝 Hexo的博文使用Markdown语言。如果你从来没用过，可以参考教程：Markdown 菜鸟教程 or Markdown语法说明(中文版)

输入如下命令创建博文：

1	$ hexo new 'name of the blog'

Hexo会在 source\_posts 下生成相关 .md 文件，每一篇博客对应一个 .md 文件，直接编辑博文对应的文件即可。

如果你想要更改博文的模板，打开 scaffolds 文件夹，你可以看到3个默认的模板 draft.md , page.md 和 post.md ，除此之外，你还可以创建自己定制的模板。

杂七杂八

Q1：Hexo更改主题后远程网站不更新？

A：更改主题后，先执行 hexo clean，再执行 hexo g 和 hexo d。如果仍然没有变化，可能是浏览器缓存的原因。按 F12 或者鼠标右键打开 检查 , 选择 Network 之后选中 Disable cache .

Q2: 如何在博文中插入图片、视频？

A：可以参考这篇博文。因为我在写博客的时候经常需要插入很多图片和视频，所以我采取为每篇博文建立自己目录的方法。打开站点配置文 _config.yml ，修改 post_asset_folder 为 true 并保存退出。

之后每次创建博文的时候会同时生成同名的文件夹，你可以将各种资源（图片、音频等）放到这个文件夹里。在博文中引用的时候，使用以下的语法即可：

插入图片: {% asset_img <image name> <title> %}

插入视频：
    <video src='vedio source' 
       type='video/mp4' 
       controls='controls'  
       preload="auto"
       width='100%' 
       height='100%'>
    </video>

部分参数：
- autoplay 则视频在就绪后马上播放。
- controls 用户显示控件，比如播放按钮。
- width 频播放器的宽度。
- height 设置视频播放器的高度
- loop 文件完成播放后再次开始播放。 loop="loop"
- preload 视频在页面加载时进行加载，并预备播放 preload="auto"
- src 要播放的视频的 URL。