前言,可不看

本文需要一定的动手折腾能力,并且注意备份。

除非你属于爱折腾/写文语法效果与 Hexo 高度耦合/没钱等类型的用户,否则不太建议用这种静态的程序,尤其是对命令一点不懂、只想写作的。WP 用起来非常方便,自定义程度也很高,你使用时遇到 99.9%的问题别人大多早已遇到并给出解决方案,而且能给你省下无数的时间。实在不行还有些平台专门托管 WP 的,也支持绑定域名。博客是以内容为主,和程序没有直接关系,用最顺手的即可。争论苹果和梨子哪个好吃是没有意义的。

终于,我那个原本使用 PHP 的博客(实际上是基于一个论坛程序通过自己编写主题魔改而来)完蛋了。后来想想那种“免费主机”各种不方便,有时体验稀碎,故被迫更换平台。GitHub Pages 只给静态页面,这下程序也要另选。

此文将记录个人使用 Hexo 和 GitHub 搭建个人博客遇到的问题与解决方法,以备不时之需。

本文主要针对 Windows 用户,但 Hexo 配置不一定要在 Windows 系统完成。

一、安装 Git

Hexo 基于 Node.js,搭建过程中还需要使用 npm ,好在 Node.js 已自带带和 git,因此先搭建本地操作环境,安装 Node.js 和 Git。

Node.js:https://nodejs.org/zh-cn
Git:https://git-scm.com/downloads

之后一直下一步(你看得懂可以自行决定)
Git 的安装有以下过程:

  1. 声明 GPLv2 协议;
  2. 选择安装目录;
  3. 选择安装组件【从上到下为添加桌面图标、添加到右键大文件支持、检测关联文件(两个选项)、每天检查更新、将配置文件添加到 Windows 终端】【一般最后两个不选,最后一个要配合 Windows Terminal 以发挥其优势】;
  4. 选择开始菜单文件夹;
  5. 选择 Git 默认编辑器,默认是 vim(纯命令,上手较难,但熟练后极其方便)。若不选择 vim,安装后可以到我的电脑->属性->高级系统设置->高级->环境变量->系统变量->Path->编辑添加配置编辑器信息;
  6. 决定初始化新项目(仓库)的主干名字。第一种是让 Git 自己选择,名字是 master ,但将来可能会改为其他名字;第二种是自定义,默认是 main,也可以改为其他的名字。一般默认第一种;
  7. 配置环境变量。
    第一种是仅从 Git Bash 使用 Git。这个的意思就是你只能通过 Git 安装后的 Git Bash 来使用 Git ,其他第三方工具均不可。
    第二种是从命令行以及第三方软件进行 Git。字面意思,比第一种多了第三方工具的支持,比较推荐。
    第三种是从命令提示符使用 Git 和可选的 Unix 工具。选择这种将覆盖 Windows 工具,不爱折腾的还是选第二种较好;
  8. 选择 SSH 执行文件。选第一种即可;
  9. https 后端传输。如果你使用 Git 不只是为了探索 GitHub 之类的,选第一种即可;
  10. 配置行位符号转换。
    签出 Windows 样式,提交 Unix 样式的行结尾。
    按原样签出,提交 Unix 样式的行结尾。
    按原样签出,按原样提交。
    你要看不懂或无所谓的,选第一个就行了。
  11. 配置终端模拟器,这个选第一个就行;
  12. 默认 Git Pull。只是为了运行 Hexo 的话选第一个足够了;
  13. 选择一个凭证帮助程序。此处英文易懂不解释,选第一个;
  14. 额外选项。启用文件系统缓存和启用符号链接。此处自行决定;
  15. 实验性功能。求稳请勿勾选。

此时你已经安装完成 Git,接下来的 Hexo 操作最好在 Git 中完成。

二、GitHub 配置

既然要部署到 GitHub 上,需要先注册账户,免费计划足够了。使用邮箱注册 GitHub 账户,选择免费账户(Free),并完成邮件验证。

创建 Key

右键 -> Git Bash Here,设置用户名和邮箱:

1
2
git config --global user.name "GitHub 用户名"  
git config --global user.email "GitHub 邮箱"

创建 SSH 密匙:

1
ssh-keygen -t rsa -C "GitHub 邮箱"

然后一路回车。

【以上三段在输入时需保留前后英文双引号】

添加秘钥

勾选显示“隐藏的项目”,进入 “C:\Users\用户名、.ssh” 目录,用记事本打开 id_rsa.pub 文件并复制里面的内容。

登陆 GitHub ,进入 Settings 页面,选择左边栏的 SSH and GPG keys,点击 New SSH key。

Title 随便取个名字,粘贴复制的 id_rsa.pub 内容到 Key 中,点击 Add SSH key 完成添加。之后打开 Git 输入:

1
ssh -T [email protected] 

出现 “Are you sure……”,输入 yes 回车确认。显示 “Hi xxx! You’ve successfully……” 即连接成功。

创建一个仓库用于部署 Hexo

右上角,头像加号,New repository,然后仓库名必须为“用户名。github.io”,否则访问时不是 github.io 的三级域名。你也可以创建个组织,在组织里创建个仓库,此时若希望以域名访问,这个仓库须和组织名相同,和用户名无关(除非你给组织起个相同的名字),也算是一种方法。

description 选填,下面选择“Public”,创建 README,完事。之后博客地址为https://用户名。github.io。若想创建组织统一博客项目,则可用地址为https://组织名。github.io

总之如果你有域名且打算绑定的,这里仓库怎么命名都行,到时在仓库Setting->Pages中设置即可。没有域名的、想直接使用 GitHub Pages 提供的域名,直接浏览官方文档:

帐户使用组织的 GitHub Free 或 GitHub Free,存储库必须是公共的。

如果要创建用户或组织站点,则存储库必须命名为 <user>.github.io<organization>.github.io。 如果您的用户或组织名称包含大写字母,您必须小写字母。

——创建 GitHub Pages 站点

三、本地安装 Hexo

在设备里找个顺眼的地方创建个文件夹,起名随意。进入文件夹后右键选择 Git Bash Here ,然后使用 npm 安装 Hexo:

1
2
npm install -g hexo-cli  
sudo npm install -g hexo-cli【这条是给 Mac 用户的】

此处命令可能比较耗时。执行完成后便可开始初始化 Hexo:

1
2
3
4
5
hexo init      # 初始化  
npm install    # 安装相关组件
完成后输入以下命令:
hexo g   # 渲染、编译页面
hexo s   # 启动本地预览

之后访问http://localhost:4000即可预览。若更换端口(例如更换为7000端口)可输入:

1
hexo server -p 7000  

四、将 Hexo 部署到 GitHub

先安装 hexo-deployer-git:

1
npm install hexo-deployer-git --save  

然后到你存放 Hexo 文件的目录下找到“_confiy.yml”文件,打开,在末尾进行修改:

1
2
3
4
deploy:  
type: git # 不解释
repository: [email protected]: [用户名/组织名].github.io # 修改相关内容为自己的。此处可直接填写仓库地址,例如"https://github.com/user/repo"也行。
branch: master # 你可以改为 main 或其他分支

输入以下命令:

1
hexo d  

愉快地部署吧!如果你前面配置无误,访问例如https://abc.github.io(abc 替换为前面的用户名组织名即可访问你的博客。

五、绑定域名(选)

这自定义一个域名不更酷吗?追求 SEO 也更方便。域名的话请自行解决,你去买一个也好,整免费的也好,总之这一步你手头得有一个域名。

域名解析到 DNS 服务商(例如 Cloudflare)后,在 DNS 添加两道解析(保险起见)

  1. A 记录 域名 185.199.110.153【GitHub 的 ip 地址,不嫌麻烦的可以把另外几个地址也解析上】

  2. CNAME www 开头域名(写了 www 会自动创建) 上文提到的地址(所以说要有以用户名。github.io 命名的仓库或组织内至少一个以相同格式命名的仓库,能直接通过域名访问)

然后到相应的仓库中,找到 setting 选项卡,在左侧菜单找到 pages 选项卡,选择仓库路径(就是你前面在、_config.yml 里写的 master 还是 main 还是其他的)、root。若配置正确,下方会出现让你填写自定义域名的地方。写完后等个几分钟生效,若无则自行检查哪一步有没有问题。

解析生效后在 Git 中输入:

1
2
3
hexo clean   # 清除缓存  
hexo g       # 编译渲染
hexo d       # 部署

然后使用你的自定义域名看看能不能访问。
如果你不希望用组织里的这个仓库,你还可以在组织里另创建一个仓库,在 setting 里【直接带子域名输入】,例如111.abc.com,然后去 DNS 解析商那里加一条 A 记录,名称就是你填的111.abc.com,地址就是你前面填的 GitHub 的 ip。同样的,等待生效。

六、发布文章

终于完成了基本部署!
在终端写文章实在不符合我的习惯,所以安装 hexo-admin:

1
npm install hexo-admin --save  

完成后输入:

1
hexo s  

在浏览器打开localhost:4000/admin即可访问(端口号取决于你的自定义,默认不改是 4000)
然后 hexo-admin 里面的设置,你看着就会用的,不需要多讲。

七、更优雅的编辑方式(选)

本地修改即时预览

浏览 Hexo 博客时访问的是编译后的静态页面,对于自定义来说,每次修改后需要清空缓存重新编译,比较麻烦。如果我希望修改后立即生效应怎么办?Browsersync就是这样一款浏览器同步测试工具,它能够在 hexo 文件(包括PugStylus_config.yml等)修改后即刻刷新。

【Blogroot】目录下打开 Git 并输入:

1
npm install -g browser-sync # Mac、Linux 用户若遇到权限不足的问题,可尝试加上“sudo”

执行完后输入以下命令,能显示对应版本则表示成功

1
browser-sync --version

什么?无此命令?请尝试 npm 走网络代理线路,或更换为taobao 镜像源

安装 hexo 端插件,请执行

1
npm install hexo-browsersync --save

之后就和原来一样使用 hexo 三连即可,在hexo s执行时修改源文件,不出意外浏览器会自动刷新同步。

管理面板(以 Hexon 为例)

每次部署还得敲命令,虽然不难但还是麻烦。另外有些虽然操作方便的方案,但我目前没条件或不会安装,所以我在此以 Hexon 为例。地址:https://github.com/gethexon/hexon

先更换

1
2
3
npm config set registry https://registry.npmmirror.com  
npm config set registry http://mirrors.cloud.tencent.com/npm/
npm config set registry https://mirrors.huaweicloud.com/repository/npm/ # 择其一执行即可

然后验证镜像源:

1
npm config get registry

最好把 pnpm 也装一下:

1
npm install pnpm -g  

在你博客的目录下打开 Git,输入:

1
git clone https://github.com/gethexon/hexon --depth 1 

进入 hexon 目录,执行:

1
2
pnpm install # 安装依赖
pnpm run setup # 运行安装程序

等待执行,终端会展示设置项,分别是

  • 端口号(程序启动时访问端口)
  • 路径(博客主程序所在路径,例如你将 Hexo 主程序安装在D:\Hexo\blog,你的 Hexon 安装在D:\Hexo\blog\hexon,那么你应该填写的是D:\Hexo\blog)(当然,你也可以不写,直接 Enter)(如果启动后终端有显示什么{ username: 'admin', password: undefined }这样的,那就按它提示的来,如果某日发现登录失败,不妨留意下此处)
  • 用户名(不解释)
  • 登录密码(不解释。在终端输入时会自动隐藏)

全部做完后,输入:

1
pnpm run start  

然后在浏览器输入localhost:5777(默认端口为 5777),填入你先前设置的信息即可登录。
如果你先前配置没问题,而且也验证过了命令行部署且一切正常,以后你就可以放心地在这个界面进行发布、修改、创建页面、部署等基本操作了。

后记

Template render error: (unknown path)

· Error: expected end of comment, got end of file

在某些情况下(常见场景为 LaTeX 中,部分情况下 CSS 文件中)编译时控制台会报出这段错误。(实际上我是在图形化编辑器中看到这个报错,编译推送过程没有问题,但既如此,不妨解决,不留后患)

Hexo 使用了 nunjucks 渲染器,\{\#很容易被识别为注释标记(写完这段文字后我的编辑器也报错了,所以使用了\将其隔开),在实际错误复现时{#直接连起来且单独存在,即只写了半个,则控制台有很大概率会飘红。这里有以下两个解决方案:

  1. 使用\{\#包裹且不要用反引号包裹这段字符,否则还是有可能被误解析(这里为演示方便故包裹字符,且使用反斜杠转义,在实际情况下这个反斜杠是没有的,且raw标记符号外不要用反引号包裹,即尽量不使用 Markdown 代码语法)
  2. CSS 选择器(尤其是压缩后的)相关则需手动换行,总之不能让这两个字符在没有其他转义的情况下连续存在;
  3. 如果使用 LaTeX 无法避免,则可使用{'{{'\{\#'}}'}使其成为字符串