如何使用 Hexo 搭建博客
本文最后更新于 2026年6月9日 凌晨
配置运行环境
我自己使用的是 Windows 11 系统，下面的步骤都是基于 Windows 11 系统进行操作，如果是 Linux / MacOS 系统，配置运行环境的方法会有些差别，可以自行使用搜索引擎或者使用 AI 解决。
安装 MSYS2
进入 MSYS2 官网。
在官网Installation找到1、Download the installer:，点击右边的按钮进行下载，下载好后打开 MSYS2 安装包，选择好安装的位置后安装。
配置 Windows 终端
Windows 10 需在开始菜单中找到Micorsoft Store，搜索Windows Terminal进行安装。
右键桌面或者文件管理器空的位置，点击在终端中打开，在标题栏点击向下的箭头，打开 Windows 终端设置，点击添加新配置文件。
在名称中填入MSYS2 UCRT64。
在命令行填入以下内容：
1 | |
C:\msys64为安装目录，根据具体安装的目录修改。
在启动目录勾选使用父进程目录。
在图标填入以下内容：
1 | |
C:\msys64为安装目录，根据具体安装的目录修改。
保存后生效，在标题栏点击向下的箭头就可以看到MSYS2 UCRT64。
配置 MSYS2 镜像源
配置好 Windows 终端后在 Windows 终端的顶栏菜单里找到MSYS2 UCRT64，打开。
在MSYS2 UCRT64终端输入以下内容并回车。
1 | |
安装 NodeJS 等工具
1 | |
安装 Hexo
1 | |
此时博客的运行环境都准备好了，下面的命令操作都需要在配置好的 MSYS2 UCRT64 终端中进行。
配置博客
下面有部分操作可能需要科学上网并且配置终端代理才能正常进行，配置终端代理可以参考《在终端中快速设置代理 》这篇文章。
初始化 Hexo 文件夹
一般在打开 MSYS2 终端后，默认路径是在 C:/Windows/System32，这是系统路径，不能随意修改，所以需要使用 cd 命令去切换路径到其他路径，比如切换到 D 盘的根目录：
1 | |
切换到其他路径后再进行其他操作。
1 | |
如果创建 Hexo 文件夹时出现了报错，需要在进入文件夹后运行npm install重新安装依赖。
进入 Hexo 文件夹
1 | |
编辑文章模板
这里我使用 NeoVim 作为编辑器，当然可以用其他编辑器进行编辑，比如 Visual Studio Code。
Visual Studio Code 支持使用命令启动，命令是 code，下面展示的是使用 NeoVim 去编辑文件，可以将命令中的 nvim 替换成 code，这样就是用 Visual Studio Code 去打开文件。
1 | |
编辑 page.md 文件：
1 | |
以下为修改 page.md 后文件的内容变动：
1 | |
编辑 post.md 文件：
1 | |
以下为修改 post.md 后文件的内容变动：
1 | |
创建分类页面
1 | |
安装主题
1 | |
如果后续主题有更新，可使用下面的方法获取更新。
1 | |
编辑主题文件
编辑 Fluid 主题的 _config.fluid.yml 配置文件：
1 | |
以下为修改 _config.fluid.yml 后文件的内容变动：
1 | |
编辑 Hexo 主配置文件
编辑 Hexo 的 _config.yml 配置文件：
1 | |
修改 _config.yml 后文件的变动：
1 | |
编辑 tools 页面
1 | |
修改 source/tools/index.md 文件的 front-matter 内容。
1 | |
编辑 about 页面
1 | |
修改 source/about/index.md 文件的 front-matter 内容。
1 | |
博客此时就配置好了。
参考文档：
将源码上传至 Github
配置 Git
配置命令中的username和youremail@example.com需要分别修改成自己的用户名和邮箱。
1 | |
配置 Github SSH 密钥
生成 SSH 密钥。
1 | |
运行这个命令后会有一些提示信息，保持默认值，直接回车几次即可。
获取 SSH 公钥。
1 | |
把输出的整个内容复制下来。
进入 Github 页面，点击头像，选择Settings->SSH and GPG keys，点击New SSH key，在Title选项随意填，Key选项填上刚刚复制的 SSH 公钥，再点Add SSH key保存。
上传源码
在 Github 创建一个私有仓库，命名为blog，用于保存博客源码。再使用下面的命令将源码上传，注意要把git remote add部分的用户名修改成自己的用户名。
1 | |
之后如果博客有更新，运行下面的命令即可。
1 | |
如果使用git push命令出现网络问题报错导致上传仓库失败，可以将仓库的 SSH 协议链接更换成 HTTPS 协议的链接。
比如上面步骤添加到仓库的链接为git@github.com:licyk/blog.git，为 SSH 协议的链接，把这个链接换成 HTTPS 协议的链接，也就是https://github.com/licyk/blog.git，则使用下面的命令进行替换。
1 | |
Github 上的仓库可以使用 HTTPS 协议的链接或者是 SSH 协议的链接进行连接和管理。
- HTTPS 协议链接格式：
https://github.com/<用户名>/<仓库名> - SSH 协议链接格式：
git@github.com:<用户名>/<仓库名>
然后按照《使用 HTTPS 协议管理 Github 仓库 - licyk的小窝》中的方法进行配置。配置完成后先使用配置终端代理的命令，再使用git push命令，一般就能成功上传仓库了。
部署博客到网站上
下面介绍 3 种平台用于部署博客。
使用 Github Pages
获取本地的 SSH 私钥。
1 | |
将输出的整个内容复制一下。
进入博客源码的 Github 仓库，点击Settings->Secrets->Secrets and variables->Actions，在Secrets部分点击New repository secret新建一个私有变量，在Name选项填DEPLOY_PRI，在Secret填入刚刚复制的 SSH 私钥，点击Add secret保存。
在 Github 上再新建一个公有仓库，命名为用户名.github.io，如licyk.github.io。
回到本地的blog仓库，创建一个 Github Action 文件。
1 | |
写入以下内容，注意在这个文件中找到Commit Blog的部分，将GIT_URL的值修改成自己公有仓库的 SSH 地址。
1 | |
保存文件后将这个 Github Action 文件推送到 Github 上的仓库，
1 | |
再进入licyk.github.io这个仓库，在仓库的 Settings -> Pages -> Build and deployment，把 Branch 从 main 修改为 gh-pages，再点击 Save。
等待几分钟后就可以通过https://licyk.github.io访问自己搭建的博客了。
使用 Netlify
先注册一个 Netlify 帐号，通过 GitHub 注册。
注册成功后跳转到你的首页，点击 Add new site 中的 Import an existing project，点击 GitHub，与 GitHub 关联。
关联 GitHub 后在下面会出现你 GitHub 中的仓库，点击你创建的 Hexo 博客，再点击 Deploy site 上传。
上传完成会跳转到项目主页，选择 Site settings，跳转后往下滑，点击 Change site name 更改你网站的名称。
Netlify 建议在项目的 Project configuration -> Build & deploy -> Continuous deployment -> Branches and deploy contexts，把 Branch deploys 修改为 None，再点击 Save 保存配置。
使用 Vercel
先注册一个 Vercel 帐号，通过 GitHub 注册。
注册成功后跳转到你的首页，点击 New project，跳转后在 Import Git Repository 中选择你的 Hexo 博客，跳转后点击 Deploy 上传到 Vercel。
上传完成点击 Goto Dashboard 来到项目主页，选择顶部的 Settings，在 Project Name 中更改你网站的名称。
Vercel 建议在项目的 Settings -> Git -> Ignored Build Step 里，Behavior 选择 custom，Command 填写if [ ! "$VERCEL_GIT_COMMIT_REF" = "gh-pages" ]; then exit 1; else exit 0; fi，再点一下 Save。
使用 Cloudflare Pages
在 Cloudflare 注册一个账号。
登陆后在 Cloudflare 管理面板首页，点击右上角的 Add -> Pages -> Import an existing Git repository，在 Github 选项下选择 blog 仓库，再点击 Begin setup。
在 Set up builds and deployments 设置中，Project name 修改为自己的用户名，如licyk，之后后博客访问的地址就是https://licyk.pages.dev；Build command 填写 npm install hexo-cli -g; npm install; hexo generate；Build output directory 填写 public。填写完成后点击 Save and Deploy。
等待一段时间后就可以看到博客部署成功了，使用https://licyk.pages.dev就可以访问自己的博客。
使用 Gitlab Pages
获取本地的 SSH 私钥。
1 | |
将输出的整个内容复制一下。
进入博客源码的 Github 仓库，点击Settings->Secrets->Secrets and variables->Actions，在Secrets部分点击New repository secret新建一个私有变量，在Name选项填DEPLOY_PRI，在Secret填入刚刚复制的 SSH 私钥，点击Add secret保存。
如果已经做过使用 Github Pages部分的步骤，则上面的步骤可以省略。
在 Gitlab 上注册一个账号。然后点击 Gitlab 右上角的+号 -> New project/repository -> Create blank project，在 Project name 命名自己的仓库，命名格式为用户名.gitlab.io，如licyk.gitlab.io；Project URL 的 Pick a group or namespace 选项选择自己的用户名；Visibility Level 修改为 Public，最后点击 Create project。
回到本地的blog仓库，创建一个 Github Action 文件。
1 | |
写入以下内容，注意在这个文件中找到Commit Blog的部分，将GIT_URL的值修改成自己在 Gitlab 上刚刚创建的仓库的 SSH 地址。
1 | |
保存文件后将这个 Github Action 文件推送到 Github 上的仓库，
1 | |
如果已经做过使用 Github Pages部分的步骤，可以在原来的基础上修改，编辑原来的pages.yml文件。
1 | |
修改 pages.yml 文件后的改动如下：
1 | |
保存文件后将这个 Github Action 文件更新到 Github 上的仓库，
1 | |
再进入licyk.gitlab.io这个 Gitlab 仓库，在仓库左侧的 Settings -> General -> Visibility, project features, permissions -> Pages，将 Only Project Members 修改为 Everyone With Access，再点击下面的 Save Changes 按钮保存修改。
等待几分钟后就可以通过https://licyk.gitlab.io访问自己搭建的博客了。
管理博客
文章保存在博客目录的source/_posts目录中，使用的文件格式为md，编写文章使用的是 Markdown 语法，不过也允许使用 HTML 语法进行文档编写，在 Markdown 语法实现不了某些效果时可使用 HTML 语法来实现。
在每篇文章的开头为 front-matter，用于配置写作设置。
比如可以在文章开头可以看到下面的内容：
1 | |
在 front-matter 下面的部分就可以用于编写文章。
创建新文章
1 | |
本地展示网页
1 | |
安装插件
1 | |
Hexo 可用的插件可以在 Plugins | Hexo 中查看，如果安装插件后出现问题，可以通过npm uninstall <package_name> --save卸载插件。
网页特效
- 鼠标点击特效
1 | |
- 流星效果
1 | |
- 指针效果
1 | |
- 樱花飘落效果
1 | |
- 看班娘
1 | |
添加追番列表
注册 bangumi 账号并登陆。
安装 HCLonely/hexo-bilibili-bangumi。
1 | |
修改 _config.yml 文件。
1 | |
加入下面的内容，vmid根据自己的进行修改，更多的说明可以看 HCLonely/hexo-bilibili-bangumi 这个项目的文档。
1 | |
改一下 pages.yml 文件，添加刷新追番列表的命令。
1 | |
修改 pages.yml 文件后的改动如下：
1 | |
修改 _config.fluid.yml 文件，添加追番列表入口。
1 | |
修改 _config.fluid.yml 文件后的改动如下：
1 | |
修改好后就可以推送到 Github 上的 blog 仓库了。
在 Netlify 上需要修改一下部署命令，在项目的 Site configuration -> Build & deploy -> Build settings -> Configure，把 Build command 修改成npm install hexo-cli -g; npm install hexo-bilibili-bangumi -g; npm install -g; npm install; hexo bangumi -u; npm run build，再点一下 Save 保存设置。
在 Vercel 上也需要修改部署命令，在项目的 Settings -> General -> Build & Development Settings，勾选 Build command 右边的 Override，填写hexo bangumi -u; hexo generate，再勾选 Install command 右边的 Override，填写npm install hexo-cli -g; npm install hexo-bilibili-bangumi -g; npm install -g; npm install，最后点击 Save 保存，
添加 Mermaid 流程图支持
修改 _config.fluid.yml 文件，启用 Mermaid 流程图。
1 | |
修改 _config.fluid.yml 文件后的改动如下：
1 | |
现在就可以在文章中使用 Mermaid 流程图了。
如果需要在某个文章使用 Mermaid 流程图，则在文章的 front-matter 添加下面的配置。
1 | |
使用 Mermaid 的方式如下：
1 | |
或者在代码块中的开头声明mermaid也可以使用 Mermaid 流程图。
1 | |
添加数学公式支持
安装 hexo-math 插件。
1 | |
现在就可以在文章中使用数学公式了。
KaTeX 语法：
1 | |
MathJax 语法：
1 | |
配置站点地图
站点地图用于主动帮助搜索引擎爬取网站内容，告诉搜索引擎哪个页面很重要。
下面提供 2 种方法配置站点地图。
配置站点方法只能使用其中一种，如果需要切换另一种配置站点方法，需要将原来配置站点地图的配置删除，并且使用npm uninstall <Hexo 插件名> --save命令卸载原来的站点地图插件。
使用 hexo-generator-seo-friendly-sitemap 插件
安装 hexo-generator-seo-friendly-sitemap 插件：
1 | |
修改 _config.yml 配置文件：
1 | |
加入下面的内容：
1 | |
如果想让某篇文章不加入站点地图，则在文章的 front-matter 添加下面的配置。
1 | |
使用 hexo-generator-sitemap 插件
安装 hexo-generator-sitemap 插件：
1 | |
下载站点地图模板：
1 | |
修改 _config.yml 配置文件：
1 | |
加入下面的内容：
1 | |
如果想让某篇文章不加入站点地图，则在文章的 front-matter 添加下面的配置。
1 | |
配置 Atom / RSS 订阅源
Atom / RSS 订阅源可用于推送文章内容更新。
安装 hexo-generator-feed 插件：
1 | |
修改 _config.yml 配置文件：
1 | |
加入下面的内容：
1 | |
修改 _config.fluid.yml 文件，添加追番列表入口。
1 | |
修改 _config.fluid.yml 文件后的改动如下：
1 | |
本地实时预览修改结果
在本地修改并预览结果时总是需要重新运行命令，此时可以通过安装 hexo-browsersync 插件实现保存修改后自动更新网页。
1 | |
如何使用 Hexo 搭建博客
https://licyk.netlify.app/2024/06/26/how-to-deploy-hexo/