Hexo 脚手架使用指南

发表于 分类于
详解本站 8 个 Hexo 脚手架（post、tech、note、link、book、original、draft、page）的适用场景与使用方法，包含新建命令、占位变量、草稿发布流程，以及 Next 8.29.1 下真正生效的 front-matter 字段速查。

脚手架（Scaffold）是 hexo new 建文章时套用的模板。选对脚手架，标题、分类、目录、版权等头部字段和正文骨架都会自动生成，无需每次重复填写。本文介绍本站配置好的 8 个脚手架以及完整的写作流程。

一、快速上手

新建文章的命令格式为：

1
hexo new [布局] "文章标题"
  • 布局 就是脚手架名（即 scaffolds/ 目录下文件的名字，不含 .md），可省略，默认是 post。
  • 执行后 Hexo 会读取对应脚手架、替换变量，在 source/_posts/ 下生成文件。

例如用技术排错模板写一篇 Nginx 排查记录：

1
hexo new tech "OpenResty worker 崩溃排查"

会生成 source/_posts/OpenResty-worker-崩溃排查.md（文件名由标题自动转换），其中已包含完整的头部参数和「背景→环境→排查→根因→解决→验证」正文骨架。

本地实时预览：

1
hexo s        # 等同于 hexo server，默认 http://localhost:4000/

二、脚手架总览

本站共有 8 个脚手架，按使用频率分为三类：

2.1 文章类

命令布局 适用内容 目录 版权 特点
post 通用文章，拿不准时用它 开 开 字段最全的基础模板
tech 技术排错 / 教程 开 开 固定排错结构与环境信息块
note 学习笔记、知识点整理 开 开 默认开启数学公式，含示例
link 分享外部链接、转载推荐 关 关 标题在首页直接跳转外链
book 读书笔记 开 开 书籍信息表 + 摘录 + 行动清单
original 图文 / 图集类原创 开 开 内置图集、置顶、打赏字段

本站全站关闭评论：所有脚手架的 comments 均为 false，且主题配置中未启用任何评论系统（comments.active 留空）。如日后想重新开启，需先在 _config.next.yml 配置评论服务，再把对应文章的 comments 改为 true。

2.2 草稿类

命令布局 适用内容 特点
draft 日记、随笔、未成文想法 默认关闭评论 / 目录 / 版权，生成在 source/_drafts/

2.3 页面类

命令布局 适用内容 特点
page 「关于」「友链」「留言板」等独立页面 生成 source/<名称>/index.md，支持自定义链接

三、各脚手架详解

3.1 post —— 通用文章

1
hexo new post "我的文章"     # post 可省略：hexo new "我的文章"

最通用的模板，包含标题、时间、标签、分类、评论、目录、版权、关键词和描述。当一篇文章不属于下面任何专门类型时，用它即可。

3.2 tech —— 技术排错 / 教程

1
hexo new tech "Nginx 502 排查记录"

专为「问题解决型」技术文章设计，正文骨架固定为：

  1. 背景与现象：问题表现、报错、影响范围
  2. 环境信息：系统、版本、配置
  3. 排查过程：定位 → 假设 → 验证，保留命令与输出
  4. 根因：点明根本原因，区分现象与根因
  5. 解决方案：可直接使用的配置 / 代码
  6. 验证：如何确认修复生效
  7. 参考：引用链接

这套结构既方便读者复现思路，也方便自己日后回看。建议标题带上技术点和现象，便于搜索。

3.3 note —— 学习笔记

1
hexo new note "Lua 闭包小结"

适合整理某个知识点。默认 mathjax: true（数学公式在构建时由服务端渲染为 SVG），并预置了公式、Mermaid 流程图、代码的写法示例。标签固定为「技术笔记」，分类为「学习笔记」，可按需修改。

Mermaid 流程图只有全局开关，不支持单篇开启。需要用流程图时，先在 _config.next.yml 中设置 mermaid.enable: true。

1
hexo new link "值得一读的 LuaJIT 优化文章"

用于分享外部好文、工具或资讯，只需在头部填写 link 字段：

1
link: https://example.com/the-article

它利用了 Next 主题原生的 Link Post 能力：

  • 在首页 / 列表页，点击文章标题会直接跳转到外部地址（标题旁带外链图标）；
  • 进入文章详情页仍可看到你写的推荐理由或批注。

因为是分享他人内容，该模板默认关闭评论与版权声明。

3.5 book —— 读书笔记

1
hexo new book "《深入理解计算机系统》读书笔记"

包含「书籍信息表 → 一句话总结 → 核心观点 → 原文摘录 → 我的思考 → 行动清单」的结构，并内置待办列表用于记录读完后要实践的事。

3.6 original —— 图文原创

1
hexo new original "西藏之行"

面向图集 / 图文内容，预置了 Next 8 中真正生效的字段：

1
2
3
4
5
6
sticky: 100          # 置顶权重，数字越大越靠前，0 或删除表示不置顶
photos:              # 图集，字段名必须是 photos（不是 gallery）
  - /images/1.jpg
  - /images/2.jpg
reward_settings:     # 单篇打赏（与全局配置合并）
  enable: true

3.7 draft —— 草稿与日记

1
hexo new draft "周末随手记"

文件生成在 source/_drafts/ 而非 _posts，默认不会被发布到正式页面，适合写半成品或私密日记。模板默认关闭评论、目录和版权。

写完后用 publish 发布为正式文章：

1
2
hexo publish draft "周末随手记"
# 会从 source/_drafts/ 移到 source/_posts/

本地想临时预览草稿，启动时加上 --draft：

1
hexo s --draft

3.8 page —— 独立页面

1
hexo new page "about"

生成的是 source/about/index.md，用于「关于我」「友情链接」「留言板」等不属于文章流的页面，通常会在导航菜单中挂一个入口。permalink 已通过变量自动生成（如 /about/）。

四、占位变量

脚手架中的双花括号是占位符，hexo new 时会自动替换：

变量 含义 示例
{{ title }} 新建时传入的文章标题 Nginx 502 排查
{{ date }} 当前日期时间 2026-10-29 18:10:00
{{ slug }} 由标题转换的 URL 别名 nginx-502

例如 page.md 中的 permalink: /{{ slug }}/，执行 hexo new page about 后会变成 permalink: /about/。

不要在脚手架里使用 `` 这类没有赋值的变量——hexo new 不会传入 author，渲染后会留下一个空的 author: 字段。只用上表三个变量即可。

五、头部字段速查（Next 8.29.1）

本站使用 Next 主题 8.29.1，不少网上旧教程的字段已失效。下面是经实测真正生效的常用 front-matter 字段：

5.1 推荐写法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
title: 文章标题
date: 2026-10-29 18:10:00
updated: 2026-10-29 18:10:00
tags:
    - 标签一
    - 标签二
categories:
    - 分类
comments: false         # 是否开启评论（本站全站关闭，保持 false）
copyright: true         # 是否显示版权声明，false 为关闭
mathjax: false          # 是否渲染数学公式
link:                   # 仅 link 模板：外链地址
sticky: 100             # 置顶权重，>0 置顶
photos:                 # 图集
    - /images/a.jpg
keywords: 关键词1,关键词2
description: 文章摘要，用于 SEO 与首页简介
toc:                    # 目录必须写成对象，会与全局配置合并
    enable: true
    number: true
    max_depth: 6
---

5.2 目录（TOC）的正确写法

Next 8 会把头部的 toc 与全局 toc 配置做对象合并，因此必须写成嵌套对象：

1
2
3
4
toc:
    enable: true       # 是否显示目录
    number: true       # 是否显示序号
    max_depth: 6       # 解析到第几级标题

5.3 已失效 / 应避免的写法

旧写法 问题 正确做法
toc: true / toc: false 布尔值无法可靠覆盖对象配置 用 toc: { enable: true/false }
toc_number: true Next 8 不读取此字段 toc: { number: true }
toc_depth: 3 不读取 toc: { max_depth: 3 }
toc_style_simple 无对应功能 删除
aside: true、sidebar: auto Next 8 已无此单篇控制 删除，侧边栏由全局配置管理
mermaid: true Mermaid 仅全局开关 在 _config.next.yml 开启
top: true 依赖第三方置顶插件（本站未装） 用原生 sticky: 权重
reward: true 字段名不符 reward_settings: { enable: true }
gallery: 字段名不符 用 photos:
header_image、wechat_subtitle Next 8 不支持 删除
author: {{ author }} 变量无值会留空 删除

六、完整写作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 选合适的脚手架新建
hexo new tech "OpenResty worker 崩溃排查"

# 2. 本地实时预览（带草稿）
hexo s --draft

# 3. 如果是草稿，写完后发布
hexo publish draft "周末随手记"

# 4. 清理并生成静态文件
hexo clean && hexo g

# 5. 部署
hexo d

也可以把生成和部署合并为一条命令：

1
hexo clean && hexo g && hexo d

七、自定义脚手架

如果现有模板都不合适，可以直接在 scaffolds/ 目录下新建一个 .md 文件，文件名就是布局名。例如新建 scaffolds/interview.md 后：

1
hexo new interview "某某公司面经"

即可套用自定义模板。模板内容就是一篇「带占位变量的文章」，头部字段参考第五节即可。

选型建议：日常排错记录用 tech，学完一个知识点用 note，看到好文用 link，读完一本书用 book，其余用 post，随手写的先丢进 draft。