利用HEXO+GithubPages搭建自己的静态博客

前言

准备趁着这个寒假系统的学习一下色彩科学和计算机图形学,这样有助于我更好的调色

为了记录和分享我新学到的知识,搭建一个知识博客是有必要的,知识分享类博客侧重体系的构建,所以它应该对Markdown与$\LaTeX$有很好的原生支持,这样有助于我把Obsidian中的知识库迁移过来,而且它应该足够轻量,易于分发与备份

(我可不希望它像wordpress那样数据库冗杂且备份文件经常无法恢复以至于我换了个云服务供应商就丢失了写了八年的博客😭)

基于上述考量,在尝试了HEXO,Gridea,Typecho这几个主流的博客平台后,我选择了基于 Node.js框架的Hexo,作为一款静态博客框架,HEXO能够将网站内容预先渲染为 HTML 文件,这与传统的动态博客不同,后者依赖于数据库和服务器端脚本来动态渲染,由于内容以静态文件形式存储和分发,所以它可以加载的更快,且可以很便捷的git到GitHub Pages 等托管服务

这篇文章记录了我搭建这套博客的过程,如果你也想拥有一套自己的博客系统,希望它能够帮到你😉

需要声明的是,我是在macOS上搭建的,不过对于Win来说大同小异

ok那我们开始吧

准备工作

注册GitHub 账号

我们需要把生成的html文件git到Repository中,你需要前往GitHub官网注册一个自己的账号

安装 Git

请提前部署好git环境

部署Node.js环境

去官网下载即可,不再赘述

下载完成后在Terminal中输入以下命令检测版本确保安装成功

node -v

你应该会得到类似 这样的output

域名购买(非必要)

通过国内的云服务供应商购买域名会更便宜,但需要备案,我个人用的是腾讯云

选择国外的供应商则无需备案,比如Cloudflare

确保自己拥有良好的科学上网环境

我们需要访问github的服务器,而这个过程需要绕过一堵无形的墙,u know

方法不再赘述,八仙过海各显神通

比如你甚至可以通过修改hosts来突破DNS污染)

安装HEXO

1.在本地创建安装目录,比如这是我的目录:

如果你和我一样把HEXO框架安装在了iCloud/OneDrive的同步文件夹下,请记得勾选“保留下载/始终保留在此设备”

截屏2025-01-23 18.53.54

2.通过cd命令切换到该目录:

cd /Users/sqren/Desktop/StrtusJourney/myblog

3.通过npm安装hexo:

npm install -g hexo-cli 

如果你和我得到了类似的output:

截屏2025-01-21 11.04.48

这是由于当前用户没有权限在 /usr/local/lib/node_modules 目录下安装全局的npm包,如果不希望在系统目录下安装 npm 包,可以将 npm 的全局安装路径修改为你自己用户目录下的某个位置

1.首先,创建一个目录来存放全局安装的 npm 包:

mkdir ~/.npm-global

2.告诉 npm 使用这个新目录来安装全局包:

npm config set prefix '~/.npm-global'

3.编辑 .bash_profile.zshrc 文件,加入以下内容:

export PATH=~/.npm-global/bin:$PATH

4.重新加载配置文件:

source ~/.bash_profile

5.再次运行安装命令

npm install hexo-cli -g

如图:

image-20250123185042301

在我们选定的安装目录下可以看到Hexo CLI:

截屏2025-01-21 11.16.56

安装完成后,初始化我们的博客,输入:

hexo init blog

不出意外的话这个时候又要出意外了

截屏2025-01-23 19.01.51

看报错信息,提示需要在 Hexo 项目的根目录下运行 npm install 来安装项目所需的依赖包

之前只是安装了 Hexo CLI,现在需要安装 Hexo 的依赖项

那么,按照它的提示👇

截屏2025-01-23 19.05.29

使用npm install命令根据 package.json 文件中的配置安装所有必需的依赖包

截屏2025-01-23 19.05.56

呐,屁用没有🤷

根据报错信息,npm 缓存目录(/Users/sqren/.npm)中包含了由 root 用户拥有的文件,这是因为之前我使用 sudo 安装过 npm 包

现在我们需要将 /Users/sqren/.npm 目录的所有权更改为当前用户:

检查当前用户的名称和对应的用户组:

id

会看到如下output:

截屏2025-01-23 22.37.24

其中:

  • uid=501(sqren) 表示当前用户是 sqren
  • gid=20(staff) 表示当前用户的用户组是 staff

修正 chown 命令:

.npm 目录及其所有内容的所有权更改为 sqren 用户和 staff 组。

sudo chown -R sqren:staff /Users/sqren/.npm

清空 npm 缓存以防出现奇奇怪怪的问题

npm cache clean --force

接下来就可以愉快的npm install了😋

截屏2025-01-23 19.19.41

安装完成后运行如下命令初始化HEXO:

HEXO init

启动HEXO本地服务

HEXO serve

如图

截屏2025-01-23 19.24.11

浏览器访问 http://localhost:4000

能进来这个页面就说明安装成功了

image-20250123192532341

配置HEXO

配置主题

cd到themes目录

直接git clone😋

截屏2025-01-23 19.31.02

随后修改_config.yml文件中的theme键值为当前主题名称:

(Hexo 有2种 _config.yml文件,一个是根目录下的全局的 _config.yml,一个是各个 theme 下的 _config.yml。前者称为站点配置文件, 后者称为主题配置文件,这里我们修改的是站点配置文件

截屏2025-01-21 14.57.41

重启本地serve,在浏览器中可以看到主题已经完成了更换

截屏2025-01-21 14.58.17

安装插件

如若需要安装插件,请使用如下命令:

npm install hexo-tag-[tag name] --save

这里以katex为例

截屏2025-01-23 19.38.07

撰写新文章

1.cd到HEXO目录

使用new命令来新建一个带有front-matter的.md文件

HEXO new 'title'

截屏2025-01-21 15.07.37

随后你可以在posts目录下打开此文档

image-20250123193652677

2.撰写完文章后使用如下命令清除缓存:

hexo clean

3.生成html文件

hexo generate

4.git

hexo deploy

5.启动本地预览服务,即可在浏览器中访问

hexo serve

使用Hexo deploy 部署到github

建立Repository

Repository的命名格式应该为<github用户名>.github.io

截屏2025-01-21 19.05.05

配置SSH

1.在仓库中获取SSH链接

截屏2025-01-23 20.40.41

2.在站点配置文件_config.yml中修改deplog的键值:

截屏2025-01-23 20.48.27

3.安装Git部署插件

npm install hexo-deployer-git --save

4.配置SSH-Key

ssh-keygen -t rsa -C <your mail>

如图👇:

截屏2025-01-23 20.55.27

添加生成的SSH key到ssh-agent:

ssh-add ~/.ssh/id_rsa

截屏2025-01-23 21.00.46

复制key,然后回到Github,进入路径user/Settings/Access/SSH and GPG keys

image-20250123210511963

Add new SSH key

image-20250123210314528

测试添加ssh是否成功

ssh -T git@github.com

如果看到Hi后面是你的用户名,就说明成功了

截屏2025-01-23 21.08.12

此时已经可以git到Repository中了

截屏2025-01-21 19.25.58

现在我们可以通过github分配的域名访问自己的静态博客:

截屏2025-01-21 19.27.16

域名解析

ping一下,延迟还不错,也不丢包(因为我开着魔法呢hhh

记住这里的ipv4地址

截屏2025-01-23 21.16.38

进入DNS解析管理页面:

A类解析到ip地址

CNAME解析到github的域名

截屏2025-01-21 19.30.59

前往Repository

Steeings/page中,输入你的domain

截屏2025-01-21 19.44.17

如果DNS check状态为successful,则会在repository生成一份CNAME文件,里面是你的domain

截屏2025-01-23 21.25.16

请将文件下载至你的本地仓库中的source文件夹,否则每次git后,会覆盖掉repository中的CNAME文件,则域名无法解析到github.io

截屏2025-01-23 21.28.04

现在,你可以愉快的写博客了

本地的markdown编辑器推荐使用Obsidian或Typora,它们都对Latex有很好的支持

结语

希望这篇文章对你有帮助,任何疑问可以通过strtus@outlook.com与我联络

enjoy😉 !