这篇文章是给自己写文章时查的 Frontmatter 字段手册。统计范围是本站当前配置：Hexo 8.1.2、Butterfly 主题、以及已安装的写作相关插件。

Frontmatter 就是每篇 Markdown 开头这段 --- 包起来的 YAML。它决定文章标题、链接、分类标签、封面、目录、加密、置顶、轮播等行为。

一、最常用模板

新文章不知道写什么字段时，用这个就够了：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
title: 文章标题
description: 一句话摘要，会显示在首页、搜索和分享信息里
keywords: Hexo, Butterfly, 关键词
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
date: 2026-05-26 12:00:00
updated: 2026-05-26 12:00:00
cover: /img/cover.webp
toc: true
toc_number: true
abbrlink: 自动生成后不要改
---

空值字段不是完全“无效”。有些主题逻辑会把空值当作 null 读取。没特殊需求时，宁可不写，也不要留一堆空字段。

二、Hexo 核心字段

这些字段是 Hexo 本身就认识的，和主题无关。

字段 类型 用途 备注
title 字符串 文章标题 最常用，建议必写
date 日期 创建时间 影响归档和排序
updated 日期 更新时间 不写时受 _config.yml 的 updated_option 影响
layout 字符串 指定布局 文章通常是 post，页面通常是 page
permalink 字符串 自定义固定链接 例如 /about-old/
categories 字符串/数组 分类 支持多分类或层级分类
tags 字符串/数组 标签 支持多个标签
excerpt 字符串 手写摘要 也可以用正文里的 <!--more-->
published 布尔值 是否发布 false 时跳过生成

示例：

1
2
3
4
5
6
7
8
9
10
11
12
---
title: Docker 部署笔记
date: 2026-05-26 12:00:00
updated: 2026-05-26 13:30:00
categories:
  - 教程
tags:
  - Docker
  - Linux
excerpt: 记录一次 Docker 部署服务的完整流程。
published: true
---

三、SEO、摘要和搜索字段

这些字段会被 Butterfly、搜索插件、Open Graph 或 Feed 间接使用。

字段 类型 用途 建议
description 字符串 首页摘要、搜索摘要、分享描述 强烈建议写
keywords 字符串/数组 页面关键词 可以写逗号分隔字符串
author 字符串 自定义作者 版权模块默认仍优先全站作者

示例：

1
2
3
4
5
---
description: 本文记录 Hexo 博客写作时常用的 Frontmatter 字段。
keywords: Hexo, Frontmatter, Butterfly
author: Jerry_FaGe
---

四、Butterfly 封面和横幅

这些字段控制文章在首页、文章页、分页卡片和分享中的视觉表现。

字段 类型 用途 备注
top_img 字符串/布尔值 文章顶部横幅 false 表示关闭顶部图
cover 字符串/布尔值 首页和侧栏文章封面 false 表示不显示封面；不写时走默认封面
cover_type 字符串 封面类型 主题会自动生成，通常不用手写
pagination_cover 字符串 上一篇/下一篇卡片封面 不写时使用 cover

示例：

1
2
3
4
5
---
top_img: /img/post-banner.webp
cover: /img/post-cover.webp
pagination_cover: /img/post-pagination.webp
---

只想关掉顶部横幅：

1
2
3
---
top_img: false
---

只想让文章在列表里不显示封面：

1
2
3
---
cover: false
---

五、Butterfly 页面行为

这些字段控制侧栏、评论、目录、代码块、音乐播放器和数学公式。

字段 类型 用途 备注
aside 布尔值 是否显示侧边栏 false 隐藏
comments 布尔值 是否显示评论 false 关闭
toc 布尔值 是否显示目录 默认跟随主题配置
toc_number 布尔值 目录是否显示编号 覆盖主题配置
toc_expand 布尔值 目录是否默认展开 当前 Butterfly 使用这个字段
toc_style_simple 布尔值 目录简洁模式 适合想减少侧栏内容时使用
highlight_shrink 布尔值 代码块是否折叠 覆盖主题代码块配置
aplayer 布尔值 当前页加载 APlayer 资源 有音乐播放器时使用
mathjax 布尔值 当前页加载 MathJax 取决于 theme.math.use
katex 布尔值 当前页加载 KaTeX 取决于 theme.math.use
noticeOutdate 布尔值 文章过期提醒 false 关闭单篇提醒

示例：

1
2
3
4
5
6
7
8
---
aside: false
comments: false
toc: true
toc_number: true
toc_expand: true
highlight_shrink: false
---

数学公式文章：

1
2
3
---
mathjax: true
---

老文章里有 auto_open 字段，但当前 Butterfly 目录默认展开对应的是 toc_expand。旧字段可以留作历史参考，新文章优先用 toc_expand。

六、Butterfly 版权模块

这些字段只影响文章底部的版权卡片。

字段 类型 用途 备注
copyright 布尔值 是否显示版权模块 false 关闭
copyright_author 字符串 版权作者 不写时使用全站作者
copyright_author_href 字符串 作者链接 可写主页或 GitHub
copyright_url 字符串 文章链接 不写时使用当前文章永久链接
license 字符串 版权协议文字 覆盖主题默认协议
license_url 字符串 协议链接 覆盖主题默认协议链接

示例：

1
2
3
4
5
6
7
---
copyright: true
copyright_author: Jerry_FaGe
copyright_author_href: https://github.com/Jerry-FaGe
license: CC BY-NC-SA 4.0
license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/
---

如果某篇文章不想显示版权模块：

1
2
3
---
copyright: false
---

七、Butterfly 特殊页面字段

这些字段不常用于普通文章，主要给特殊页面使用。

字段 类型 用途 备注
type 字符串 触发特殊页面布局 如 404、shuoshuo
orderby 字符串 标签页排序 标签云页面可用，默认 random
order 数字 标签页排序方向 标签云页面可用
custom_colors 布尔值 标签云自定义颜色 标签页面可用
shuoshuo_url 字符串 说说页面外部数据地址 type: shuoshuo 时使用
limit 对象 说说页面限制配置 只在说说页面逻辑里读取

示例：

1
2
3
4
5
6
7
---
title: 说说
type: shuoshuo
shuoshuo_url: /data/shuoshuo.json
limit:
  initial: 10
---

八、系列文章字段

Butterfly 侧边栏支持系列文章卡片，当前主题会读取 series。

1
2
3
---
series: Docker 实战
---

同一个 series 名称的文章会被归到同一组。适合连续教程，例如：

系列名 适用场景
Docker 实战 Docker 入门、部署、排错
Hexo 博客折腾记 主题配置、插件配置、写作规范
AI API 记录 OpenAI、Function Calling、工具调用

九、已安装插件字段

本站永久链接配置是：

1
permalink: posts/:abbrlink.html

所以文章里会有：

1
2
3
---
abbrlink: ddeeb867
---

abbrlink 生成后不要随便改。改了以后文章 URL 会变，旧链接可能失效。

2. hexo-generator-index

首页排序支持 sticky：

1
2
3
---
sticky: 10
---

规则很简单：数字越大，越靠前。不写就是普通文章。

3. hexo-butterfly-swiper

首页轮播插件读取 swiper_index：

1
2
3
---
swiper_index: 2
---

规则同样是数字越大越靠前。插件只收集 swiper_index 为真值的文章。

4. 随机文章脚本

本站自定义随机文章脚本会读取 random：

1
2
3
---
random: false
---

设置成 false 后，这篇文章不会进入随机文章池。

5. 自定义百度 Sitemap

本站 scripts/generators/baidu-sitemap.js 会读取 baidusitemap：

1
2
3
---
baidusitemap: false
---

设置成 false 后，这篇文章不会进入自定义百度 sitemap。

十、文章加密字段

本站安装的是 hexo-blog-encrypt v4。只要 password 有值，文章就会被加密。

基础示例：

1
2
3
4
5
6
7
---
password: 123456
theme: xray
abstract: 有东西被加密了, 请输入密码查看.
message: 您好, 这里需要密码.
wrong_pass_message: 抱歉, 这个密码看着不太对, 请再试试.
---

完整字段：

字段 类型 用途 备注
password 字符串/数字 加密密码 空字符串明确表示不加密
theme 字符串 加密框主题 无效主题会回退 default
abstract 字符串 加密后摘要 首页和摘要位置显示
message 字符串 密码输入提示 显示在加密框里
wrong_pass_message 字符串 密码错误提示 v4 推荐使用这个
wrong_hash_message 字符串 解密失败提示 v4 已废弃，会被当作 wrong_pass_message
silent 布尔值 静默插件日志 有需要再用
autoSave 布尔值 保存解密状态 浏览器端行为
decryptButton 对象 解密按钮配置 可设置按钮显示和文字
kdf 对象 PBKDF2 配置 iterations 推荐 600000+

高级示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
password: very-strong-password
theme: xray
abstract: 私密内容，需要密码。
message: 输入密码继续阅读
wrong_pass_message: 密码不对，再试一次。
autoSave: true
decryptButton:
  show: true
  text: 解锁
kdf:
  iterations: 600000
---

十一、旧字段和历史字段

这些字段在旧文章里出现过，但当前启用的 Butterfly 主题或 Hexo 核心里没有检出直接读取逻辑。可以保留作历史参考，新文章不建议优先使用。

字段 当前状态 替代建议
hide(hidden) 站内旧约定字段 暂无明确读取逻辑
auto_open 旧 TOC 字段 用 toc_expand
copyright_info 旧版权声明字段 用 license / license_url

十二、按场景抄作业

普通技术文章

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
title: 技术文章标题
description: 一句话说明这篇文章解决什么问题。
keywords: Docker, Linux, 部署
tags:
  - Docker
  - Linux
categories:
  - 教程
date: 2026-05-26 12:00:00
cover: /img/docker-cover.webp
toc: true
toc_number: true
---

想放首页靠前

1
2
3
4
---
sticky: 5
swiper_index: 2
---

不想要评论和侧栏

1
2
3
4
---
aside: false
comments: false
---

长文教程

1
2
3
4
5
6
7
---
toc: true
toc_number: true
toc_expand: true
highlight_shrink: false
series: Hexo 博客折腾记
---

私密备忘录

1
2
3
4
5
6
7
8
9
---
password: 123456
abstract: 有东西被加密了, 请输入密码查看.
message: 您好, 这里需要密码.
wrong_pass_message: 抱歉, 这个密码看着不太对, 请再试试.
random: false
baidusitemap: false
comments: false
---

十三、字段来源速记

来源 字段
Hexo 核心 title、date、updated、layout、permalink、categories、tags、excerpt、published
Butterfly 主题 description、keywords、top_img、cover、pagination_cover、aside、comments、toc、toc_number、toc_expand、toc_style_simple、highlight_shrink、aplayer、mathjax、katex、noticeOutdate、copyright、copyright_author、copyright_author_href、copyright_url、license、license_url、type、series
hexo-abbrlink abbrlink
hexo-generator-index sticky
hexo-butterfly-swiper swiper_index
hexo-blog-encrypt password、theme、abstract、message、wrong_pass_message、wrong_hash_message、silent、autoSave、decryptButton、kdf
站内脚本 random、baidusitemap

写文章时的原则：常用字段少写、关键字段写准、生成后的 abbrlink 不乱改。