起飞！基于Hexo框架的个人博客搭建与部署实录

本文最后更新于：2023年4月27日 晚上

近来，博主PhD生涯遭遇重大挫折。在幻灭感和虚无感的双重挤压下，精神备受煎熬。自忖学术道路难以为继，奋然决心技术转型。

在 Web 2.0 时代，个人博客是一块难得的精神自留地，同时也是记录个人成长的良好载体。以建立个人博客作为探索技术转型路的开端，颇有象征意义，也挺 Cool。

博主作为小白，决定选择基于一种相对成熟、社区相对活跃的开源框架，即 Hexo，来搭建个人博客。大概花了一天时间才折腾出一点眉目。

1. 为什么是 Hexo

对博主而言，入坑 Hexo 是因为注意到几位自己关注的技术大佬在用它做博客，且主题酷炫，颇对我胃口。经过进一步了解，发现 Hexo 生成的是静态页面，可托管于 Github，因此搭建成本不高；且教程简明、丰富，容易实操。同时，Hexo能满足技术博客最基本的 Markdown 语法支持。因此，博主选择了利用 Hexo 搭建自己的第一个博客。

事实上，博客框架还有其它选择，如 Wordpress，Hugo，Jekyll 等。静态博客框架的选择可以参考 Static Site Generators。这些，就留到以后再折腾吧···

2. 准备工作

搭建与部署主要参考 Hexo 的官方文档和知乎上的技术分享。但实际操作过程中的问题也层出不穷。

安装 Hexo 需要首先安装 Node.js 和 Git。博主的系统环境是 64 位 Windows 10，安装这两款软件还是比较顺利，参考知乎的技术分享即可，也没有遇到什么大坑。博主安装的版本分别是 Node.js v18.16.0 LTS 和 Git v2.40.6。成功配置后，可以在命令行界面输入 npm -v 查看 npm 版本；同时，可以在任何文件路径下点击鼠标右键(或者 Shift + 右键)，点击 Git Bash Here，打开Git Bash 命令行界面。进一步的配置，可以在 Git Bash 命令行中进行，主要有两个问题值得注意。

  • npm 包的安装路径

    npm， 即 Node Package Manager。查看 npm 的默认安装路径可以用指令

    1
    npm config ls

    Windows 10下默认的全局安装路径通常是 C:\Users\<user name>\AppData\Roaming\npm, 担心占用C盘空间的话可以通过

    1
    2
    npm config set prefix "File Path" 
    npm config set cache "File Path"

    进行设置 （另外还需要相应的配置环境变量）, 具体过程可以参考这篇文章。npm大概有以下几种不同的包安装方式，可以按需使用：

    1
    2
    3
    npm install package #安装到项目路径，不在package.json中写入依赖
    npm install package -g #安装到全局目录下
    npm install package --save #安装到项目路径下，并写入依赖

  • Git 与 Github 的绑定

    使用 Git 上传文件至 Github 时，为了免除每次输入口令的麻烦，通常使用 SSH 公钥登录。需要首先生成公钥，然后在 Github 中添加公钥。具体步骤如下：

    1. Git 中生成密钥: 
      1
      ssh-kengen -t rsa
    2. 在密钥目录下，查看公钥： 
      1
      cat id_rsa.pub
    3. Ctrl + Insert 复制公钥 (Git 中的复制和粘贴分别是 Ctrl + Insert 和 Shift + Insert)；
    4. 在 Github 个人主页中，依次点击 Settings -> SSH and GPG Keys -> New SSH key -> 粘贴 id_rsa.pub 至 Key 文本框内-> Add SSH Key；
    5. 在 Git Bash 中验证是否成功: 
      1
      ssh -T git@github.com
    6. 验证用户名和邮箱 
      1
      2
      git config --global user.mail "<mail address>"
      git config --global user.name "<UserName>"

3. 安装 Hexo

完成环境的准备工作后，可以使用 npm 全局安装 Hexo：

1
npm install -g hexo-cli

默认应该是安装最新版。博主安装的版本是 v6.3.0。然后，建立一个文件夹用于存放博客文件，在该文件夹下打开 Git Bash，运行以下指令

1
2
3
hexo init  #在文档路径下建立初始化必要文件
hexo g  #生成静态页面
hexo s  #将页面部署到本地

顺利完成的话（通常本地查看不太会出现问题），便可以在 localhost:4000 查看生成的静态页面以及默认生成的第一篇 Hello World 博客。

Hexo 初始化后的文件夹将出现 scaffolds, source, source/_posts, themes 等几个文件夹， 以及 _config.yml 等几个文件。以下重点介绍几个文件(夹)的功能：

  • scaffolds：存储文章模板。默认有 draft.md, page.md, post.md。主要是设置文章的 Front-matter, 具体支持的参数和关键字随主题而异；
  • source：存储用户资源， 包括 Markdown 文档、图片等。在使用Git上传时， 除 _posts 文件夹外， 其它以 “_” 开头的文件(夹)会被自动忽略。
  • public： 用于存放解析后的文件；
  • package.json: 已安装的程序信息；
  • _config.yml: 页面的配置信息。可以设置主题、页面标题等内容；

4. 一键部署 Hexo 到 Github

首先，在 Github 创建自己的 Github Pages。过程很简单，即新建以 <UserName>.github.io 为名称的仓库，并设置为 Public， 即可。

接下来，在 _config.yml 文件中添加以下内容:

1
2
3
4
deploy:
  type: git
  repo: git@github.com：<UserName>/<UserName>.github.io.git
  branch: main

在博客文件夹下安装插件：

1
npm install hexo-deployer-git --save

运行以下指令:

1
2
3
hexo clean #清楚缓存文件db.json和已生成的静态文件public
hexo g #生成网站静态文件
hexo d #将静态文件推送到指定的远端仓库分支中，并且完全覆盖仓库内容

完成之后， 在浏览器中，即可输入 https://<UserName>.github.io 访问博客网页了。

  • Tips：关于 hexo d 失败的几种解决方案
    • 出现 Recv failure 等无法上传的问题： 通常跟网络环境有关系。博主之前使用的 https 指定仓库地址，频繁无法上传页面。不管是否配置代理，都不好使。在 _config.yml 中将 https 换成 git@ 的方式之后没有再报错了。
    • 注意提前验证邮箱和用户名，参考 Part 2 与 Github 绑定部分。
    • 尝试清除缓存文件重新上传， 即删除 .deploy_git 文件，重新运行清除、生成、上传命令。

5. 域名解析

通过 Github Pages 托管的个人博客域名是固定的，不够个性。私以为，只有拥有名片般域名的博客才是完整的。博主遂斥重金 (200多块钱，可以用 3 年，其实也还好。。。) 在 Godaddy 购买了该域名。

域名提供商也可以选择国内的腾讯云或者阿里云等。域名的价格通常第一年会有优惠，后面几年会高一些，随个人消费能力而定了。通常的规律是简短且含义丰富的域名价格高；热门后缀，如 .ai 等价格高。

购买域名后需要在域名提供商处添加 DNS 解析规则，具体可以参考 Github 文档。 简单来说，需要添加 4 条 A 类型记录, 4 条 AAAA 类型记录和 1 条 CNAME 记录, 添加不完整可能出现域名解析失败。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# A 类型记录
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

# AAAA 类型记录
2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

# CNAME 类型记录
<UserName>.github.io

在博客文件夹里的 source 文件夹中，添加 CNAME 文件，写入不带 www 的域名 (这样可以同时以不带 www 和带 www 的方式访问页面)。

完成以上步骤，重新生成并部署 Hexo 至 Github 即可。

  • Tips: 网页突然出现域名解析失败
    • Github 似乎会检查 DNS， 若没有通过 DNS 检查，网页可能会出现无法查看的问题，具体可以在仓库中点击 Settings -> Pages, 查看 Custom domain。
    • 域名似乎还需要通过 Verify。 在个人主页中，点击 Settings -> Pages。 按照要求在域名服务商处添加一条 TXT 类型的记录，然后点击 Verify。 通过后会显示 Verified。
    • 检查 CNAME 文件是否正确。

注意：博主配置完后发现链接无法升级到 https (安全性还是很有必要的)。经过一番检查，发现从 Godaddy 购买的域名会默认添加一条 Parked 记录。删除该条记录后， Github会自动升级链接。事实上，在 DNS 解析中，不应该保留多余的 A 类型记录。

结语

回想个人博客部署的过程，发现还是蛮曲折的，事毕之后也是颇为激动。事实上，以上的步骤还只完成了基本的搭建和部署，进一步还可以做个性化定制，添加自己喜欢的主题等。总之，作为一个开始，希望自己费心搭建的博客能见证我的成长和变化，发挥价值。

博客搭建
#Hexo #日常
起飞！基于Hexo框架的个人博客搭建与部署实录
https://xuming234.work/2023-hexo-framework-deployment.html
作者
Ming Xu
发布于
2023年4月24日
许可协议