如何正确使用安知鱼主题在 Hexo 上写博客

本文整理自 Hexo 官方文档 与 安知鱼主题官方文档，结合自己的踩坑经历，梳理出一条从「装环境」到「发文章」的完整路径。这也是本博客的第一篇文章。

写在前面：Hexo 与安知鱼是什么关系？

Hexo 是一个快速、简洁且高效的静态博客框架：用 Markdown 写文章，几秒内就能生成静态网页。它的核心逻辑包括文章、页面、分类、标签、主题渲染等。

安知鱼（AnZhiYu） 则是基于 Hexo 的一款「简单、美丽」的主题，由 安知鱼 开发维护，改自知名的 hexo-theme-butterfly。

官方文档有一句话值得默念三遍：

使用这个主题之前，你应该明白它是一个 Hexo 主题，它的基本逻辑离不开 Hexo。关于如何新建分类、如何新建标签这些问题，应该在使用之前就从互联网或官方文档了解详情。

也就是说：先有 Hexo，后有主题。Hexo 管「怎么写、怎么组织内容」，主题只管「长什么样」。理解了这一点，后面 90% 的问题都能自己定位。

安知鱼的主题特性非常丰富，挑几个日常写作最关心的：

  • 页面组件懒加载（pjax）、图片懒加载
  • 多种代码高亮方案、LaTeX 数学公式、mermaid 流程图
  • 本地搜索 / Algolia 搜索
  • 暗色模式、文章字数统计、AI 摘要
  • 音乐球、瀑布流相册、即刻说说等娱乐功能
  • 内置多款评论插件与访问统计

第一步：环境准备

按 Hexo 官方文档，只需要两个前置软件：

软件 要求
Node.js 不低于 10.13，建议 12.0 以上（Hexo 8.x 建议 20.19+）
Git 任意较新版本

Windows 直接下载安装包即可（Node.js 安装时记得勾选 Add to PATH），然后全局安装 Hexo：

1
npm install -g hexo-cli

第二步：建站

找一个干净的目录，初始化博客：

1
2
3
hexo init my-blog
cd my-blog
npm install

初始化完成后，整个博客的骨架就长这样：

1
2
3
4
5
6
7
8
my-blog
├── _config.yml        # 站点配置（Hexo 全局配置）
├── package.json
├── scaffolds          # 文章/页面模板
├── source             # 你的内容（文章、页面、资源）
│   ├── _posts         # 所有博文放这里
│   └── ...
└── themes             # 主题放这里

此时跑 hexo s 就能在 http://localhost:4000 看到默认主题的博客了。

第三步：安装安知鱼主题

推荐 GitHub 方式安装稳定版（在博客根目录执行）：

1
git clone -b main https://github.com/anzhiyu-c/hexo-theme-anzhiyu.git themes/anzhiyu

拉不下来可以用代理地址，或者直接去 release 页面 下载压缩包解压到 themes/anzhiyu。Hexo 5.0 以上也可以 npm i hexo-theme-anzhiyu。

然后做三件事：

1. 启用主题。 打开站点配置 _config.yml，修改：

1
theme: anzhiyu

2. 安装渲染插件。 安知鱼使用 pug 和 stylus，必须装对应渲染器：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

3. 建立覆盖配置（重要！）。 把 themes/anzhiyu/_config.yml 复制到博客根目录，重命名为 _config.anzhiyu.yml。以后所有主题改动都改这个文件，升级主题时不会丢配置：

1
2
3
# macOS / Linux
cp -rf ./themes/anzhiyu/_config.yml ./_config.anzhiyu.yml
# Windows 手动复制改名即可

本地预览：

1
hexo clean && hexo g && hexo s

这里引出一个关键概念，也是官方文档反复强调的：

  • 站点配置：博客根目录的 _config.yml，Hexo 全局生效。
  • 主题配置：_config.anzhiyu.yml（推荐）或 themes/anzhiyu/_config.yml。
  • _config.anzhiyu.yml 的优先级高于 themes/anzhiyu/_config.yml；凡是存在于覆盖文件里的配置，改原文件是无效的。

记牢「站点配置 ≠ 主题配置」，能避开一大半的配置玄学。

第四步：日常写作的正确姿势

新建文章与页面

1
2
hexo new "我的第一篇文章"    # 生成文章 → source/_posts/我的第一篇文章.md
hexo new page "about"        # 生成页面 → source/about/index.md

文章和页面是两种内容：文章有时间线，进首页列表、归档和 RSS；页面是独立的静态页（关于我、友情链接、标签页等），不随时间沉底。

吃透 Front-matter

每篇 .md 文件顶部用一对 --- 包裹的区域就是 front-matter，用 YAML 语法声明元信息：

1
2
3
4
5
6
7
8
9
10
11
---
title: 文章标题
date: 2026-08-07 16:00:00   # 必填，决定归档排序
tags: [Hexo, 教程]           # 标签，平铺结构
categories: 建站             # 分类，支持层级
top: true                    # 置顶（主题增强）
cover: /img/cover.jpg        # 封面图（主题增强）
toc: true                    # 显示目录
math: true                   # 启用数学公式
---
正文从这里开始……

几条保命语法规则：

  1. --- 必须是文件第一行，前面不能有空行或字符；
  2. 冒号后面必须有一个空格；
  3. 缩进只能用空格（推荐 2 个），不能用 Tab；
  4. 含 :、#、[ 等特殊字符的字符串加引号；
  5. tags、categories、published 这几个字段只对文章有效，写在页面上会被直接忽略。

写作三件套命令

1
2
3
hexo clean   # 清除缓存（改配置后必跑）
hexo g       # 生成静态文件
hexo s       # 本地预览（localhost:4000）

养成习惯：每次改完配置或文章，先 hexo clean 再 hexo g && hexo s，本地确认没问题再部署。

第五步：我的踩坑实录

既然是第一篇文章，就把自己踩的坑也记下来，希望能帮到后来者。

坑 1：top_img.indexOf is not a function

生成时报错，指向主题模板里对 top_img 调用字符串方法。原因是我在配置/front-matter 里写了裸的 top_img: true，而这版主题的模板只接受字符串路径或 false。改成下面任一写法即可：

1
2
top_img: /img/index_top.jpg   # 方案 A：给真实图片路径
top_img: false                # 方案 B：关闭顶部图

教训：YAML 里 true 是布尔值不是字符串，模板拿到布尔值调 .indexOf 必炸。

坑 2：改了主题配置没生效

原因多半是你在 themes/anzhiyu/_config.yml 里改，但覆盖文件 _config.anzhiyu.yml 里存在同名配置，优先级更高，把改动盖掉了。想确认覆盖是否生效，可以 hexo g --debug 看输出。

坑 3：页面结果和本地不一致

页面效果一律以本地 hexo s 为准。部署后的异常大多是线上缓存，确认无报错后等一会儿刷新即可。

第六步：部署（可选）

Hexo 支持一键部署到 GitHub Pages 等平台，核心流程：

1
npm install hexo-deployer-git --save

然后在站点配置里填好仓库信息：

1
2
3
4
deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io.git
  branch: main

之后一条命令完成部署：

1
hexo clean && hexo g && hexo d

写在最后

回过头看，这套流程其实就四件事：

  1. 装环境：Node.js + Git + hexo-cli；
  2. 装主题：git clone → 改 theme: → 装 pug/stylus 渲染器 → 建覆盖配置；
  3. 写文章：hexo new → 填好 front-matter → Markdown 正文；
  4. 发出去：hexo clean && hexo g && hexo d。

正如安知鱼文档所说，主题文档只讲主题范围内的用法，Hexo 本身的问题（分类、标签、命令）请回归 Hexo 官方文档。两份文档配合使用，才是最省时间的姿势。

参考资料