利用 Github pages 和 hexo 搭建自己的博客

前言

Hello world!

这是我在新博客的第一篇博客文章，记录这个博客是如何搭建的。由于我并非专业人士，仅简略记录我的搭建过程和遇到的问题，并且不详细解释每一步的操作。如有疑问，请访问参考部分。（以及使用 AI）

目前该博客处于美化阶段，主要内容为替换默认图片（背景，图标等）。博主艺术创作能力有限，欢迎提供帮助。

20260501 upd：已经有几位朋友按照我的博客搭建自己的博客了，同时也反馈了一些问题。比如，这篇博客写于 2024 年，而软件、github 和主题都在不断更新，请务必参考官方文档。不过，正因已经到了 2026 年，技术博客基本上快是时代的眼泪了，因为它们很难维持实效性。建议直接使用 AI 帮忙搭建、解决问题（让 AI 联网阅读官方最新的文档），如果你有 Codex/Claude Code 等 agent 博客网站基本上一句话就能搞定，还可以帮你美化。鉴于这个原因，本篇博客中的内容可能已经过时，请谨慎参考。

当然，我这两年的技术也有了些提升，因此我仍然加了些原理性的内容，希望让新手更好地理解整个搭建过程。

搭建博客

博客可以像搭建访问量较大的网站一样实现。一般来说，搭建网站需要购买服务器、域名、备案、购买云服务器等一系列繁琐的流程，如果要制作静态网页还需要自己手搓或者利用 WordPress 等 CMS 系统。而用 GitHub Pages 和 Hexo 搭建博客，可以快速搭建个人博客，而且不需要购买服务器、域名、备案等繁琐的流程。

Github Pages 是 Github 提供的静态页面托管服务，可以直接将静态网页托管到 Github Pages 仓库中，然后通过域名访问。相较于其他静态页面托管服务，Github Pages 免费、稳定、安全，但是在国内访问和加载资源较慢，适合个人博客。

理论上说，你完全可以自己手搓 HTML 页面和脚本完成博客。但对于像我这样的新手或者重点在成果而非过程的人来说，使用现成的框架和工具可以节省大量时间。Hexo 是一个基于 Node.js 的静态博客框架，它可以快速生成静态网页，并且可以用 Git 部署到 GitHub Pages。

20260501 upd：即便是使用 Hexo 这样的框架，仍然需要一定的技术能力和耐心来搭建和维护博客，比手机上的笔记还是重得多。尤其是，如果你想在一个新的设备上写博客的话，你需要完整的配置环境，包括安装 Node.js、Hexo、Git 等工具，并且需要将博客仓库克隆到本地，进行编辑和部署。这段话是在我换了新电脑时写的。

创建 GitHub Page

登录 Github（如果没有的话就注册一个，注意用户名和邮箱，将会频繁用到），创建一个名为 username.github.io 的仓库，其中 username 是你的 GitHub 用户名。这就是你的 GitHub Pages 站点的仓库。可以通过访问 https://username.github.io 来访问你站点的 index.html 文件。

安装配置 Git

Git 是一个版本管理工具。注意，它本身并不负责在网上存储你的仓库文件，负责存储的是 Github/gitee/GitLab 等平台，在 Git 中配置好账户后可以向这些平台通信。从 Git 官网 下载安装。

正如我上面说的，给 Git 配置你的用户名和邮箱。在命令行输入：

1
2

git config --global user.name "user_name"   # user_name填入GitHub用户名
git config --global user.email "user_email" # user_email填入GitHub注册的邮箱

检查：查看已设置的用户名和邮箱，在命令行输入：

1
2

git config user.name
git config user.email

配置 SSH key

SSH 是一种安全的远程登录协议，可以让你（Hexo 等本地软件）通过命令行与 GitHub 进行通信。配置 SSH key 可以让你在命令行中使用 Git 命令来管理你的 GitHub 仓库，而不需要每次都输入用户名和密码。

给本机生成 SSH key：

1

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

命令行中会让你继续填写保存的位置、key 的密码什么的，三个默认设置就可以，不需要密码（否则的话，得在某些我也不知道的地方填密码）。在 C 盘 .../Users/your_user_name/.ssh 目录下找到 id_rsa.pub 公钥文件，复制里面的内容，在 GitHub_Settings_keys 上新建添加 SSH key。（直接点击前面的超链接可以打开你已经登录账户的 GitHub SSH key 设置页面）

本地输入以下命令检测是否配置成功：

1

ssh -T git@github.com

如果出现 Hi username! You've successfully authenticated, but GitHub does not provide shell access. 字样，则配置成功。

如果返回 Connection closed by 20.205.243.166 port 22类似字样，有可能是代理的问题。请关闭你的代理清除缓存（重启）并重试。

这一步成功让 Hexo 可以通过你机器的 SSH key 来访问你的 GitHub 仓库，从而快捷部署博客。因此，如果你切换了设备，就得重新配置 SSH key。

安装 Node.js

从 Node.js 官网 下载安装。

有多种安装方式，推荐使用安装器（.msi文件）安装。

安装之后命令行中应当可用 npm 命令，输入 npm -v 来检查是否安装成功。如果不成功，尝试重启设备，或者检查环境变量中是否包含 Node.js 的安装路径，如没有则在环境变量中添加 Node.js 的安装路径。如果仍然遇到红色的 因为在此系统上禁止运行脚本 等错误，用管理员权限打开 PowerShell 输入 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 来允许执行脚本。

安装 Hexo

在命令行中输入以下命令安装 Hexo：

1

npm install -g hexo-cli

创建一个文件夹作为你的博客配置文件夹所在位置，并在其中打开命令行。输入

1
2
3

hexo init blog
cd blog
npm install

即可创建你的博客项目。其中 blog 是你的博客文件夹名。之后所有的操作都在 blog 文件夹中进行。

之后如果要在设备中迁移，不用再次初始化了。

配置 Hexo

安装 hexo-deployer-git 插件，用于部署到 GitHub Pages。

1

npm install hexo-deployer-git --save

编辑根目录下的 _config.yml 文件，配置你的 deploy 部分站点信息。

1
2
3
4

deploy:
  type: git
  repository: git@github.com:StarCried/StarCried.github.io.git  #你的仓库地址
  branch: main

现在你已经搭建好了你的博客，可以进行本地预览和部署。

如果你本地预览正常而部署后静态资源未加载（比如主题格式混乱），请检查你的 _config.yml 文件中的 url 和 deploy 部分是否正确。

除了 deploy 部分，你还需要配置其他部分，包括 site 等。

使用 Hexo

Hexo 有以下常用命令：

1
2
3
4
5
6

hexo init     # 创建一个新的 Hexo 站点
hexo clean    # 清除缓存文件
hexo generate # 生成静态文件
hexo deploy   # 部署到 GitHub Pages
hexo server   # 启动本地预览服务器
hexo new <layout> <title>  # 创建新文章

Hexo 的工作流程是，在项目中进行主题配置（_config.yml 文件），用 hexo new 命令创建新文章、在 _posts 文件夹中编写文章后，运行 hexo generate 命令生成静态文件（要部署到 Github Pages 的文件，在 .deply_git 文件夹中），然后运行 hexo deploy 命令部署到 GitHub Pages。

如果你使用 VSCode 打开配置文件夹，可以安装 Hexo 拓展，然后用 Ctrl + Shift + P 打开命令面板，输入 Hexo 来使用 Hexo 的命令。

美化博客

Hexo 官方提供了丰富的主题，你可以在 官方主题发布页 中查看。注意，大多数主题是由社区提供的，其配置方式和插件支持等千差万别，请根据自己的需求选择适合的主题。我是用的是 volantis 主题，阅读文档以自定义美化。

主题安装

参考 官方文档 安装主题。

主题文件夹下也有一个配置文件 /node_modules/hexo-theme-volantis/_config.yml。在博客根目录的 _config.yml 文件旁边新建一个文件 _config.volantis.yml ，这个文件中的配置信息优先级高于主题文件夹中的配置文件。将配置文件复制过来修改，以免配置丢失。

使用 npm 安装主题的配置文件在如上位置，而使用传统方式安装的主题配置文件在 theme 文件夹下。

遵循官方文档，修改配置文件 _config.volantis.yml 中的配置信息即可。

使用资源

在配置文件中，你可能经常看到图标使用 volantis-static 位置的图片资源。这是主题的官方静态资源库，可以直接使用里面的资源。

如果你想上传自己的资源，最简单的办法是使用图床或者另开一个 github 仓库，然后将图片链接替换到配置文件中。如果你觉得加载速度太慢，也可以使用 cdn 服务，参见文档。

密码插件

如果你想加密一些你的文章，使得只有正确输入密码之后才可以查看，那么你可以使用hexo-blog-encrypt 插件。

只需要按照文档安装和配置即可。不过每次上传文章前需要清除缓存。

数学公式

Hexo 自带 MathJax 插件，可以渲染数学公式。volantis 主题默认启用该插件，你只需要在每个用到数学公式的文章前的 front-matter 中添加 plugins: [mathjax] 就可以使用数学公式了。

使用的话，在文章中使用 $ 和 $$ 来包裹公式即可……吗？

对单行公式来说是这样的。但是对于多行公式，由于默认渲染器的原因（hexo-renderer-marked），会错误解读 // 优先为 Markdown 语法，导致渲染失败。（VScode 编辑器的 Markdown to PDF 插件也会遇到这个问题）

你可以根据官方文档选择自己喜欢的方式解决。

我解决的办法是更换渲染引擎。然而不同渲染引擎解决的方法不同，依然有可能遇到插件冲突问题。建议使用 pandoc。

我第一次更换了 syzoj-renderer：

1
2

yarn remove hexo-renderer-marked
yarn add hexo-renderer-syzoj-renderer

1

npm install --global yarn

它解决了多行渲染的问题。然而，这导致了标签插件没有正常被渲染。由于该插件有过和 Pjax 插件冲突的先例，怀疑是渲染逻辑的硬伤，于是更换了 pandoc：

1
2

yarn remove hexo-renderer-syzoj-renderer
npm install hexo-renderer-pandoc --save

同时，你还需要下载 pandoc 并将其导入环境变量或加入配置文件。

在 _config.yml 中添加：

1
2

pandoc:
  pandoc_path: C:\Users\PC\AppData\Local\Pandoc\pandoc.exe # 替换为填入你的pandoc安装路径

测试，解决了所有已知问题，并且浏览时右键公式可以复制源代码，十分方便。

图床

如果你想在博客中插入图片，那么你需要一个图床。将图片上传到图床后，你可以直接引用链接到博客里。

你可以直接将图片上传到博客仓库，然后引用，但 GitHub 的国内加载速度实在太慢。在多次试用之后，我找到了一个比较合适的图床网站：imagehub 图床，它免费、快速，但稳定性未知。

Live2D 插件

除了主题整合的可以直接使用的插件，你也可以自己装额外插件。在进阶玩法里有一个看板娘插件（实际是将 Live2D 模型渲染到页面上）。我想更进一步使用微光模型。然而模型还没影子

待更新。

转移博客

之前我主要使用的博客是博客园，需要将内容进行转移。参见 博客园 Cnblogs 迁移到 Github Pages。

参考

• GitHub-Hexo-从零开始搭建个人博客
• GitHub Pages + Hexo搭建个人博客网站，史上最全教程
• volantis 官方文档
• hexo 官方文档