前言

前两篇分别介绍了 Hexo 的基础知识与插件生态。本文作为系列第三篇，聚焦官方文档中相对进阶但实用的功能模块：标签插件、数据文件夹、服务器配置、生成器原理和国际化支持。这些功能在日常博客维护和主题开发中经常用到，但容易被忽略。

一、标签插件

标签插件是 Hexo 内置的模板标签，可以在 Markdown 文章中直接使用，无需安装额外插件。它们的语法与普通 Markdown 不同，需要直接写在 Markdown 中（不能被 Markdown 语法包裹）。

1.1 引用块（blockquote）

用于添加引文，支持作者、来源、链接：

text
1
{% blockquote [作者[, 来源]] [链接] [链接标题] %}内容{% endblockquote %}

示例：

text
1
2
3
{% blockquote David Levithan, Wide Awake %}
Do not just seek happiness for yourself. Seek happiness for all.
{% endblockquote %}

1.2 代码块（codeblock）

比普通 ``` 代码块功能更丰富，支持标题、链接、行号高亮：

text
1
{% codeblock [标题] [lang:语言] [URL] [链接文字] [line_number:false] [mark:1,4-7] %}代码{% endcodeblock %}

也支持反引号语法：

text
1
2
3
``` [language] [title] [url] [link text]
代码
```

1.3 已废弃标签（Hexo 7.0+）

以下标签在 Hexo 7.0.0 中已移除，需使用 hexo-tag-embed 插件替代：

标签	状态
{% jsfiddle %}	❌ 已移除
{% gist %}	❌ 已移除
{% youtube %}	❌ 已移除
{% vimeo %}	❌ 已移除

1.4 文章引用

在文章中引用其他文章，自动解析路径：

text
1
2
3
{% post_link 文章文件名 %}
{% post_link 文章文件名 '自定义文字' %}
{% post_link 文章文件名 '标题' false %}

这是系列文章间互相引用的常用方式。

1.4 资源引用

配合资源文件夹使用，引用文章的附件资源：

text
1
2
3
{% asset_img 图片名 %}
{% asset_img 图片名 宽度 高度 %}
{% asset_link 文件名 %}

1.5 其他标签

标签	用途
...	阻止内容被渲染
{% iframe URL [宽] [高] %}	嵌入 iframe
{% img class /path [宽] [高] "标题" "替代文字" %}	插入图片
{% link 文字 URL [external] %}	插入链接
{% include_code [标题] lang:语言 path %}	嵌入代码文件
<!-- more -->	文章摘要截断点

二、数据文件夹

Hexo 提供两种数据文件机制，用于在模板中使用自定义数据。

2.1 source/_data 目录

在 source/_data/ 下创建 YAML 或 JSON 文件，即可在模板中通过 site.data.文件名 访问：

yaml
1
2
3
4
# source/_data/menu.yml
Home: /
Gallery: /gallery/
Archives: /archives/

模板中使用（EJS / Pug 语法对照）：

ejs
1
2
3
<% for (var link in site.data.menu) { %>
  <a href="<%= site.data.menu[link] %>"><%= link %></a>
<% } %>

pug
1
2
each link, name in site.data.menu
  a(href=link)= name

典型用途：自定义导航菜单、友情链接列表、站点配置数据等。

2.2 资源文件夹（post_asset_folder）

在 _config.yml 中启用 post_asset_folder: true 后，每篇文章可以有同名的资源目录：

text
1
2
3
4
5
source/_posts/
├── my-article.md
└── my-article/
    ├── image1.png
    └── data.csv

文章中引用：

text
1
{% asset_img image1.png %}

三、服务器

3.1 基本使用

bash
1
2
3
4
5
npm install hexo-server --save
hexo server          # 默认 http://localhost:4000
hexo server -p 5000  # 指定端口
hexo server -i 127.0.0.1  # 指定 IP
hexo server -s       # 静态模式（不监视文件变动）

3.2 后台运行

hexo server 默认在前台运行，终端关闭后进程会被杀掉。需要后台持久运行时：

bash
1
2
3
4
5
# 脱离终端会话
setsid hexo server -p 4000 > /tmp/hexo.log 2>&1 &

# 或使用 nohup
nohup hexo server -p 4000 > /tmp/hexo.log 2>&1 &

3.3 常用场景

场景	命令
本地开发	hexo server
局域网访问	hexo server -i 0.0.0.0
调试生产构建	hexo generate && hexo server -s
端口被占用	hexo server -p 5000
后台运行	setsid hexo server -p 4000 > /tmp/hexo.log 2>&1 &

3.4 静态模式与动态模式

• 动态模式（默认）：监视文件变动，修改 Markdown 后自动刷新
• 静态模式（-s）：只处理 public/ 目录，需要先 hexo generate，适合模拟生产环境

3.5 注意事项

• hexo server 的 0.0.0.0 监听在生产环境不安全，应通过 nginx 反代
• 静态模式下修改源文件后需要重新 hexo generate 才能生效
• 后台运行时建议使用 setsid 而非 nohup，以完全脱离终端会话

四、生成器

Hexo 的生成器（Generator）负责将 source/ 目录中的文件转换为 public/ 目录中的静态文件。理解生成器的工作原理，有助于排查构建问题和开发自定义功能。

4.1 内置生成器

生成器	功能	输出
index	首页分页	index.html, page/2/index.html
archive	归档页	archives/index.html
tag	标签归档	tags/tag-name/index.html
category	分类归档	categories/cat-name/index.html
post	文章页	2026/06/xxxxx/index.html
page	独立页面	about/index.html

4.2 自定义生成器

插件可以注册自定义生成器，通过 hexo.extend.generator.register 注册：

javascript
1
2
3
4
5
6
7
hexo.extend.generator.register('my-generator', function(locals) {
  return {
    path: 'output-file.html',
    data: locals,
    layout: 'my-layout'
  };
});

实际项目中常用的分页生成器借助 hexo-pagination 模块：

javascript
1
2
3
4
5
6
7
8
9
10
const pagination = require("hexo-pagination");

module.exports = function (locals) {
  const posts = locals.posts.sort(this.config.index_generator.order_by);
  return pagination('', posts, {
    format: 'page/%d/',
    layout: ['index'],
    perPage: this.config.index_generator.per_page,
  });
};

例如我的 DoraTiger 主题就自建了 11 个生成器（sitemap、robots、404、about、tags、categories、redirect、terms、privacy、local-search、index），替代了多个第三方插件。这些生成器在 scripts/generators/lib/ 下独立实现，通过 scripts/generators/index.js 统一注册。

4.3 数据流

text
1
source/ → Generator → data 对象 → Layout 模板 → public/

Generator 接收 locals（全站数据），输出 {path, data, layout} 对象，Hexo 根据 layout 查找对应的模板文件进行渲染。

五、国际化（i18n）

5.1 语言文件

在 languages/ 目录下创建语言文件：

text
1
2
3
4
languages/
├── zh-Hans.yml    # 简体中文
├── zh-Hant.yml    # 繁体中文
└── en.yml         # 英文

文件内容为键值对：

yaml
1
2
3
4
5
# languages/zh-Hans.yml
post.created: 创建于
post.modified: 更新于
post.untitled: 无标题
home.read_more: 阅读更多

5.2 模板中使用

pug
1
2
3
4
5
// Pug 模板
span= _p("post.created") + " " + date(post.date)

// EJS 模板
<span><%= _p("post.created") %> <%= date(post.date) %></span>

5.3 语言检测

根据 _config.yml 中的 language 设置自动选择：

yaml
1
2
# _config.yml
language: zh-Hans

Hexo 会优先查找精确匹配（zh-Hans.yml），找不到则回退到默认语言。

六、总结

本文补充了 Hexo 官方文档中相对进阶但实用的功能模块。标签插件让文章排版更灵活，数据文件夹支持模板数据复用，服务器配置影响开发体验，生成器是 Hexo 构建的核心机制，国际化则为多语言站点提供基础。下一篇将进入自建主题的实战开发。

参考

• Hexo 官方文档
• Hexo 标签插件
• Hexo 数据文件
• Hexo 服务器
• Hexo 模版