Hexo 安装指南 - 须臾自省

2930 字

15 分钟

Hexo 安装指南

2021-12-11

建站

Hexo

Hexo 1 安装指南#

前言#

采用的配置如下：

系统：Ubuntu
服务器：Nginx
博客框架：Hexo

2021/12/12 我并没有将博客部署到 Github 上，主要是因为 Github 在国内的访问不太可靠，且之前我有租华为的云服务器。

2022/08/13 - 我使用以上配置一年多了，还是推荐本地编写博客，然后远端发布，远程更新文章还是太麻烦了。

2022/08/15 - 思考了两天，尝试了一下把博客部署到 github 上，没啥问题，就是有点慢，还是等原来服务器过期吧…

安装 Nginx#

安装 Nginx：

1
sudo apt install nginx

Nginx 配置的参考：

1
# Default server configuration
2
server {
3
        listen 80 default_server;
4
        listen [::]:80 default_server;
5

6
        # Hexo
7
        root /var/www/hexo/public; #hexo下的public文件夹
8

9
        server_name _;
10

11
        index index.html index.htm index.nginx-debian.html;
12
}

安装 Git#

Linux (Ubuntu, Debian)： sudo apt-get install git-core

Windows：git 官网

安装 Node.js 与 npm¹#

Ubuntu#

apt 包管理工具

1
apt install nodejs npm

NodeSource 脚本

注意安装版本，如果使用 Hexo 发现如下问题可以用更低的版本：

Hexo-nodejs版本过高报错.png

写文章的时候，Node.js 的稳定版本为 16.13.1 LTS。

Hexo-配置方案-nodejs版本.png

获取并执行 NodeSource 安装脚本（setup_ 后接需要的 Node.js 版本，例如 setup_14.x。）：

1
curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -

安装 Node.js 和 npm ：

1
apt install nodejs

Windows#

Hexo-Windows安装nodejs.png

前往 nodejs 官网获取对应的 .msi 安装包，如果官网无法打开，可以尝试从镜像网站获取。

安装 Hexo#

参考了 Hexo 的官方文档²，完成上面步骤后，用 npm 安装 Hexo：

1
npm install -g hexo-cli

创建并进入指定目录：

1
mkdir /var/www/hexo
2
cd /var/www/hexo

由于需要使用 Nginx 进行代理，所以放在 /var/www 中，如果放在其他文件夹内，需要重新配置权限。

Hexo 初始化指定文件夹：

1
hexo init
2
npm install

通过 Hexo 生成一次静态文件：

1
hexo g

在当前目录下的 public 文件夹内看到生成的文件。

到这里，安装就基本结束了，如果修改过 Nginx 的配置文件，尤其是 root /var/www/hexo/public 根目录的设置，就可以直接通过域名或IP地址访问博客了。

Hexo-配置方案-HelloWorld.png

2023.07.11 Windows 环境下使用 hexo g 指令，出现报错 统上禁止运行脚本。有关详细信息，请参阅 https:/go.microso

打开 win11 开始界面（Win键）
搜索 powershell
设置 允许本地 PowerShell 脚本在不签名的情况下运行
打开 更改执行策略，以允许本地 PowerShell 脚本在未签名的情况下运行。远程脚本需要签名。

部署到 Github 仓库#

Step1. 创建 username.github.io 仓库

使用对应 github 账户，在该账户下创建一个同名的 repository，名称为 username.github.io。

最终 repository 的访问链接为 https://github.com/username/username.github.io.git

Step2. 安装 hexo-deployer-git

进入 Hexo 项目所在文件夹，安装用于远程部署的插件：

1
npm install hexo-deployer-git

安装完成后，进入 Hexo 的 _config.yml 文件进行配置：

1
# Deployment
2
### Docs: https://hexo.io/docs/one-command-deployment
3
deploy:
4
  type: git
5
  repo: https://github.com/username/username.github.io.git
6
  branch: master

保存并退出。

Step3. 远程部署到 Github

进入 Hexo 项目所在文件夹，输入如下指令：

1
hexo d

之后，项目就会部署到对应的 Github 仓库中，中间会有 Github 确认部署用的密钥，同意即可。

Step4. 访问

输入网址 https://username.github.io/ 即可访问。

Hexo 2 基本配置#

前言#

这里就讲一下我对 Hexo 的一些基本配置，详细的可以参照官方文档¹。

模板#

在 Hexo 目录下的 scaffolds 保存三种写作模板，分别对于 draft(草稿)、page(页面) 以及 post(文章)。

这里我在 draft 以及 post 模板头部里增加了 categories: 这一项，用来生成文章分类。

这里推荐一下菜鸟教程的 MarkDown 教程。

资源#

同在 Hexo 目录下的 source 文件夹是用来存储文章、图片等需要用于生成网站的资源。

我在 source 下就专门建立了 \images\、\videos\等文件夹用于存储网站资源。

使用我这种方法，由于路径问题，会到导致你无法在你写文档时看到图片阅览，可以使用 hexo-asset-images 插件来解决，具体方法我就不进行讲述了，建议直接百度。

配置#

除开主题相关的，大部分配置都可以在 _config.yml 文件中进行修改。

参数方面仍然建议是查看 Hexo 文档中关于配置的内容²，官方有中文，并且讲述非常细。

我这里列一下除 Site 网站信息以外我所做的改动：

URL - url: https://zodiaclab.top
URL - permalink: //
Writing - future: false
Themes - theme: next (如果没有修改主题就默认即可)

插件#

我为了保持 Hexo 的整洁，在摸透结构之间并不准备安装太多插件。

所以我只安装了 hexo-renderer-markdown-it 用来支持更多的 markdown 语法。

先卸载原有的 hexo-renderer-marked：

1
npm uninstall hexo-renderer-marked

再安装 hexo-renderer-markdown-it

1
npm install hexo-renderer-markdown-it

结论#

Hexo 在不安装插件、主题的情况下，其实并没有太多可以进行配置的内容，大多数配置方法你都能在官方的文档上进行找到，我这里也就提供了不涉及主题的情况下，我 Hexo 的基本配置。

Hexo 3 Next主题#

前言#

Next: Stay Simple. Stay NexT.

Next 是 Hexo 博客中一个非常流行的简约主题¹，并且支持大量插件以及二次魔改。

这里我记录一下 Hexo 下 Next 的安装过程，以及相关的基础配置方案。

安装 Next#

Hexo 中提供了两种安装 Next 的方法，分别是 npm 和 github²，两种方法都非常简单，但从 npm 上获取的有一些问题，我之后会提到，所以个人推荐使用 github 这个下载方案。

npm#

使用 npm 指令，从商店中下载 Next 主题：

1
cd hexo
2
npm install hexo-theme-next

完成后，你就能在 ./node_modules/ 中找到 hexo-theme-next 文件夹，个人建议把这个个文件夹改名为 next 后，放到 ./themes 当中。

如果后续需要更新就运行如下指令即可：

1
npm update hexo-theme-next

github#

进入 hexo 根目录后，直接 clone Next 仓库即可。

1
cd hexo
2
git clone https://github.com/theme-next/hexo-theme-next themes/next

后续更新可以使用官方推荐的方法：

1
cd themes/next
2
git pull

修改配置文件#

在完成安装后，还需要对 ./_config.yml 文件进行配置，才能使主题生效：

1
### Themes: https://hexo.io/themes/
2
theme: next

直接修改主题为 next 即可。

然后清除网站静态文件，并重新生成：

1
hexo clean && hexo g

完成后，你再进行访问，就能看到有 Next 主题的网页。

Hexo-配置方案-HelloWorld.png

Hexo 4 更多Markdown语法#

前言#

我现在用的 Markdown 渲染器是 hexo-renderer-markdown-it，相比较 Hexo 默认的渲染器 hexo-renderer-marked，它的渲染速度更快、功能更丰富，例如它支持注脚、下划线 等高级语法，这是默认的渲染器所不具备的，因此写作会更加方便。

安装 hexo-renderer-markdown-it#

首先，卸载原来默认的渲染器：

1
npm uninstall hexo-renderer-marked

然后，安装 hexo-renderer-markdown-it：

1
npm install hexo-renderer-markdown-it

完成后就能用该渲染器对文本进行渲染了，但例如注脚等功能需要额外的配置。

安装 Markdown 插件#

这里我以注脚为例，演示如何安装更多配套的功能插件。

首先，安装 markdown-it-footnote 注脚插件：

1
npm install markdown-it-footnote

然后，打开 hexo 的 _config.yml 文件进行配置，在 # Extensions 行后增加如下内容：

1
# hexo-renderer-markdown-it
2
markdown:
3
  render:
4
  plugins:
5
    - markdown-it-footnote
6
  anchors:

更多的方法可以参考：【Hexo】选择更高级的Markdown渲染器

1
markdown:
2
  preset: "default"
3
  render:
4
    html: true
5
    xhtmlOut: false
6
    langPrefix: "language-"
7
    breaks: true
8
    linkify: true
9
    typographer: true
10
    quotes: "“”‘’"
11
  enable_rules:
12
  disable_rules:
13
  plugins:
14
    - markdown-it-abbr
15
    - markdown-it-cjk-breaks
16
    - markdown-it-deflist
17
    - markdown-it-emoji
18
    - markdown-it-footnote
19
    - markdown-it-ins
20
    - markdown-it-mark
21
    - markdown-it-sub
22
    - markdown-it-sup
23
    - markdown-it-checkbox
24
    - markdown-it-imsize
25
    - markdown-it-expandable
26
    - name: markdown-it-container
27
      options: success
28
    - name: markdown-it-container
29
      options: tips
30
    - name: markdown-it-container
31
      options: warning
32
    - name: markdown-it-container
33
      options: danger
34
  anchors:
35
    level: 2
36
    collisionSuffix: ""
37
    permalink: false
38
    permalinkClass: "header-anchor"
39
    permalinkSide: "left"
40
    permalinkSymbol: "¶"
41
    case: 0
42
    separator: "-"

Hexo 5 katex 数学公式渲染#

前言#

老实说如何在 hexo 中渲染数学公式卡了我非常长的时间，可能是版本问题，我试过网上很多种下载插件的方式，但都没办法用：

Hexo-无法渲染数学公式.png

我这里始终显示 CDN 接口连接超时，所以我就开始尝试使用 KaTeX 的本地渲染。

Step1: 获取 KaTeX#

前往 KaTeX/KaTeX，下载最新的 Release。

解压后将文件夹放入可访问路径中，注意：是从外部可访问的路径！

Step2: 安装 hexo-math#

首先，在 hexo 中安装 hexo-math：

1
npm install hexo-math

然后，在 hexo 的 _config.yml 配置文件中增加如下内容：

1
# hexo-math
2
math:
3
  enable: true
4
  engine: katex

Step3: 配置 hexo#

最后，我们需要将 KaTeX 的接口添加到 hexo 中。

这里根据安装的主题不同有所差异，例如我安装的 Next 主题，路径就是：

theml >> next >> layout >> _partials >> head >> head.swig

在 head.swig 中增加 KaTeX 的接口：

1
<link rel="stylesheet" href="xxx/katex.min.css" crossorigin="anonymous">
2
<script defer src="xxx/katex.min.js" crossorigin="anonymous"></script>
3
<script defer src="xxx/contrib/auto-render.min.js" crossorigin="anonymous"></script>

打个公式测试一下，a_1=b^1+1

$a_1=b^1+1$

其他#

注意事项#

1. 公式内容需要在一行内结束，如果换行会因为渲染器问题导致内容无法连贯（多行内容是通过<p></p>标签进行分割），使 KaTeX 按格式无法检索到公式。

2. 公式中出现了部分 Markdown 语法中的关键词，例如_、^等，渲染器会在 KaTeX 之前完成渲染，导致数学公式无法渲染。

两种方法，第一种是通过在这些符号前增加 \ 来提示渲染器跳过这些特征符号，第二种是对公式内容增加 html 标签使渲染器跳过整个公式内容的渲染，例如 <a>xxx<\a>、<p>xxx<\p>。

吐槽: 在 VS Code 里，公式增加 <p> 就无法渲染，但 <a> 可以？

单行和内联公式#

在 head.swig 中增加如下内容：

1
<script>
2
  document.addEventListener("DOMContentLoaded", function() {
3
    renderMathInElement(document.body, {
4
    delimiters: [
5
      {left: '$$', right: '$$', display: true},
6
      {left: '$', right: '$', display: false},
7
    ],
8
    throwOnError : false
9
    });
10
  });
11
</script>

添加完成后，使用 $$ 就表示单行公式，使用 $ 表示就表示行内嵌入公式（内联）。

Hexo 6 插入图片#

前言#

介绍一下 Hexo 中插入图片的两种方法，![]() 和 <img>。

Markdown 语法#

Markdown 中有标准的导入图片的语法：![]()

![图像的替代文本](图像的路径)

如果使用过类似 Typora 的 Markdown 写作工具，应该了解，当导入图片时，可以自动在该 .md 文件的路径下创建一个子文件夹，用来本地保存图片。

hexo 中默认是支持该方法的，但由于 hexo 会将该子文件夹内的图片在渲染完成后和 html 文件放在同一文件夹下，所以按原始路径无法访问，因此需要安装额外的插件。

为此，需要 hexo-asset-image 这个插件进行中间调度

step1. 修改 hexo 的 _config.yml 文件: 将 post_asset_folder: false 修改为 post_asset_folder: true

step2. 安装 hexo-asset-image 插件: npm install hexo-asset-image

step3. 创建新的文章 hexo n xxx : 在 xxx.md 的同路径下能看到同名文件夹，可以再该文件夹下保存图片

Html 标签#

Html 插入的图片方式就是通过 <img> 标签插入图像，这种方法所有的浏览器都支持，格式如下：

1
<!-- 绝对路径 -->
2
<img src="https://zodiaclab.top/images/avatar.png" />
3

4
<!-- 相对路径 -->
5
<img src="/images/avatar.png" />

<img src="https://zodiaclab.top/images/avatar.png" width = 200px /> 👇

HTML <img> 标签

img 元素向网页中嵌入一幅图像。

请注意，从技术上讲，<img> 标签并不会在网页中插入图像，而是从网页上链接图像。<img> 标签创建的是被引用图像的占位空间。

<img> 标签有两个必需的属性：src 属性和 alt 属性。

alt 规定图像的替代文本。

src 规定显示图像的 URL

结论#

个人觉得 Html 标签的方法至少在功能上比较强，像 Markdown 语法就不支持图片尺寸修改，但 Markdown 比 Html 在后期文件整理上更加简洁。