Hexo Theme Aerlume 使用指南

Aerlume 是一个基于 AirCloud 二次开发的 Hexo 主题，整体风格比较简洁，主要面向以文字阅读为主的个人博客。主题支持响应式布局、文章目录、搜索、代码高亮、图片灯箱和 Giscus 评论等功能。

这篇文章记录一下从安装主题到日常写作的基本操作，后面更换头像、404 图片或网页图标时，也可以直接回来查。

安装并启用主题

通过 npm 安装

进入 Hexo 博客根目录后执行：

npm install hexo-theme-aerlume --save

从 GitHub 安装

也可以直接将主题克隆到 themes 目录：

cd themes
git clone https://github.com/wu3227834/hexo-theme-aerlume.git hexo-theme-aerlume
cd ..

如果需要使用全局搜索，再安装搜索插件：

npm install hexo-generator-search --save

打开博客根目录的 _config.yml，启用主题和搜索：

theme: hexo-theme-aerlume

search:
  path: search.json
  field: post

这里需要注意，博客通常有两个 _config.yml：

配置文件	用途
博客根目录 _config.yml	标题、作者、头像、评论、统计和社交账号
themes/hexo-theme-aerlume/_config.yml	主题默认配置，例如本地字体

个人账号、域名、评论仓库和统计 ID 应当放在博客根目录配置中，不要写入主题
默认配置。

基础站点配置

下面是一份比较常用的配置，可以根据自己的站点信息进行修改：

title: 我的博客
subtitle: 记录技术与生活
author: Your Name
language: zh
timezone: Asia/Shanghai

url: https://example.com/
root: /

SEOTitle: 我的个人博客
description: 关于这个博客的简短介绍。
keyword: Hexo,博客,技术笔记

github_username: your-github-name

修改根目录 _config.yml 时要注意 YAML 缩进，建议统一使用两个空格，不要
混用 Tab。

自定义侧边栏头像

将头像文件放在博客站点的 source/img/ 目录：

source/img/avatar.png

然后在根目录 _config.yml 中配置：

sidebar-avatar: img/avatar.png

avatar_style:
  radius: true

sidebar-avatar 的路径是相对于 source/ 的，因此这里填写 img/avatar.png，不要写成 source/img/avatar.png。

radius: true 会显示圆形头像。如果配置了 github_username，点击头像会跳转到对应的 GitHub 主页；不希望头像可以点击时，删除或注释掉 github_username 即可。

自定义 404 页面

替换 404 图片

主题默认使用下面的图片作为 404 页面插图：

source/img/404-error.jpg

只需要使用自己的图片覆盖这个文件，然后重新生成站点即可。

修改 404 文案和结构

默认模板位于：

themes/hexo-theme-aerlume/layout/404.ejs

如果主题是通过 npm 或 Git 安装的，不建议直接修改主题文件。可以先复制到博客根目录：

mkdir -p layout
cp themes/hexo-theme-aerlume/layout/404.ejs layout/404.ejs

然后修改根目录的 layout/404.ejs：

<div class="notfound">
  <img class="notfound-img"
       src="<%= config.root %>img/404-error.jpg"
       alt="页面不存在">
  <h1 class="notfound-title">页面走丢啦</h1>
  <p class="notfound-desc">你访问的页面不存在，可能已被移动或删除。</p>
  <a class="notfound-btn" href="<%= config.root %>">返回首页</a>
</div>

这样以后升级主题时，不会覆盖自己的 404 页面。

自定义网页 icon

这里的网页 icon 分为两种：浏览器标签页图标和侧边栏导航图标。

浏览器标签页 favicon

主题默认读取：

source/img/favicon.ico

使用自己的 ICO 文件覆盖即可。更换后如果浏览器仍显示旧图标，可以执行 hexo clean 并清理浏览器缓存。

主题模板固定引用 img/favicon.ico，所以如果不准备修改 layout/_partial/head.ejs，应当保持这个文件名和路径不变。

侧边栏导航图标

侧边栏导航模板位于：

themes/hexo-theme-aerlume/layout/_partial/nav.ejs

首页、标签、归档、关于和搜索使用了下面这些 iconfont 类名：

导航项	默认类名
首页	icon-shouye1
标签	icon-biaoqian1
归档	icon-guidang2
关于	icon-guanyu2
搜索	icon-sousuo1

为了避免主题升级覆盖修改，先复制模板：

mkdir -p layout/_partial
cp themes/hexo-theme-aerlume/layout/_partial/nav.ejs layout/_partial/nav.ejs

然后在复制出来的文件中修改图标类名：

<i class="iconfont icon-shouye1"></i>

需要注意，新类名必须存在于当前主题加载的 iconfont 样式表中。随意填写一个不存在的类名，网页上不会显示对应图标。

创建标签页和关于页

首次使用主题时，可以创建标签页和关于页：

hexo new page tags
hexo new page about

修改 source/tags/index.md：

---
layout: tags
title: 标签
---

修改 source/about/index.md：

---
layout: about
title: 关于
comments: true
---

创建和编写文章

使用下面的命令创建文章：

hexo new post "文章标题"

生成的 Markdown 文件通常位于 source/_posts/。文章开头的 Front Matter
可以这样写：

---
title: 文章标题
date: 2026-09-16 10:00:00
updated: 2026-09-16 18:00:00
tags:
  - Hexo
  - 技术笔记
categories:
  - 博客搭建
description: 文章摘要，会用于 SEO 和社交分享卡片。
keywords: Hexo,Markdown,博客
comments: true
---

常见字段说明：

字段	说明
title	文章标题
date	发布时间
updated	最后更新时间，可选
tags	文章标签，可以填写多个
categories	文章分类
description	搜索引擎和分享卡片使用的摘要
keywords	文章关键词
comments	是否显示评论区
password	配合加密插件设置访问密码

常用 Markdown 语法

标题

# 一级标题
## 二级标题
### 三级标题

建议按标题层级依次使用，不要从二级标题直接跳到四级标题。Aerlume 会根据文章标题自动生成目录，标题层级清晰时目录也更容易阅读。

文字、链接和引用

普通文字

**粗体**

*斜体*

~~删除线~~

[Hexo 官方网站](https://hexo.io/)

> 这是一段引用。

`这是一段行内代码`

列表

- 第一项
- 第二项
- 第三项

1. 第一步
2. 第二步
3. 第三步

代码块

使用三个反引号包裹代码，并在开头注明语言：

```javascript
const message = 'Hello Aerlume';
console.log(message);
```

主题会对代码进行语法高亮，并在支持的代码块上显示复制和查看源码操作。

表格

| 功能 | 是否支持 | 说明 |
| --- | --- | --- |
| 文章目录 | 是 | 根据标题自动生成 |
| 图片灯箱 | 是 | 页面有图片时自动加载 |
| 搜索 | 是 | 需要安装搜索插件 |

显示效果如下：

功能	是否支持	说明
文章目录	是	根据标题自动生成
图片灯箱	是	页面有图片时自动加载
搜索	是	需要安装搜索插件

图片

站点公共图片可以放在 source/img/ 下：

![图片说明](/img/example.jpg)

开启 post_asset_folder: true 后，也可以为每篇文章建立独立资源目录：

source/_posts/example.md
source/_posts/example/image.jpg

然后在文章中使用相对路径：

![文章配图](image.jpg)

主题检测到文章中包含图片时，会自动加载图片灯箱。图片最好填写有意义的说明文字，不要只写 ![图片]，这样对无障碍阅读和搜索引擎都更友好。

如果需要控制图片宽度，也可以直接使用 HTML：

<img src="/img/example.jpg" alt="示例图片" style="width: 50%;" />

评论、搜索和文章样式

Giscus 评论

在根目录 _config.yml 中配置 Giscus：

comment:
  type: giscus
  script: |
    <script src="https://giscus.app/client.js"
            data-repo="your-name/your-repo"
            data-repo-id="YOUR_REPO_ID"
            data-category="General"
            data-category-id="YOUR_CATEGORY_ID"
            data-mapping="pathname"
            data-reactions-enabled="1"
            data-theme="preferred_color_scheme"
            data-lang="zh-CN"
            crossorigin="anonymous"
            async>
    </script>

文章 Front Matter 中还需要开启评论：

comments: true

搜索

确认已经安装：

npm install hexo-generator-search --save

然后配置：

search:
  path: search.json
  field: post

文章首行缩进

post_style:
  indent: 1

设置为 0 可以关闭首行缩进。

本地预览和排查

修改配置、模板或静态资源后，建议执行：

hexo clean
hexo generate
hexo server

然后打开：

http://localhost:4000/

预览时可以依次检查：

1. 首页标题、头像和侧边栏导航是否正常。
2. 标签页、归档页和关于页是否能打开。
3. 文章目录、表格、图片和代码块是否正常显示。
4. 搜索是否能找到文章。
5. 评论区是否加载成功。
6. 访问一个不存在的地址，检查 404 页面。

如果修改后页面没有变化，通常可以按下面的顺序排查：

1. 执行 hexo clean 清理旧的生成文件。
2. 检查 YAML 缩进和冒号后是否有空格。
3. 检查图片是否真的位于 source/ 目录下。
4. 检查 root 是否与实际部署路径一致。
5. 使用浏览器无痕窗口排除缓存影响。

写在最后

Aerlume 的配置并不复杂。站点信息放在根目录 _config.yml，文章和图片放在 source/，需要长期保留的模板修改则放在博客根目录的 layout/ 中。

按照这个原则管理文件，可以尽量避免主题升级覆盖个人配置。平时写文章时，Front Matter、标题层级和图片路径保持规范，目录、搜索、图片灯箱和 SEO 信息
就能正常工作。