Hexo 钩子生命周期

Hexo 提供了两种钩子机制来让开发者介入博客的构建流程：事件（Events） 和过滤器（Filters）。本文将按照执行顺序，逐一讲解所有钩子，并注明哪些是特定命令所独有的。

两种钩子机制概览

事件（Events）

Hexo 继承了 Node.js 的 EventEmitter，你可以通过 hexo.on() 方法监听事件，通过 hexo.emit() 方法触发事件。

// 监听事件示例
hexo.on('generateBefore', function () {
  console.log('生成即将开始...');
});

过滤器（Filters）

过滤器用于修改特定的数据，Hexo 将数据按顺序传递给过滤器，过滤器逐个修改数据。注册方式为：

hexo.extend.filter.register('过滤器名称', function (data) {
  // 修改 data
  return data;
}, priority);

priority 值越低，执行越早，默认为 10。

钩子执行顺序

第一阶段：初始化

这是所有命令都会经过的入口阶段。ready 事件和 after_init 过滤器在功能上类似，都在初始化完成后触发。

第二阶段：处理源文件（Processing）

这个阶段 Hexo 会扫描并处理 source 文件夹中的源文件（如 Markdown 文章）。

注意：before_post_render 和 after_post_render 是针对每篇文章逐个执行的，而不是只执行一次。

第三阶段：生成静态文件（Generation）

这个阶段 Hexo 的生成器（Generator）会创建静态 HTML 文件。

说明：

• hexo generate 和 hexo server 在启动阶段都会完整经历上述第 10-16 步。
• after_render 过滤器会在每一次渲染完成后执行，不仅仅是在最终页面生成时。这意味着它也可能在渲染文章摘要、主题的局部模板（如侧边栏）等场景下被触发。如果你的逻辑只需在完整页面上生效，需要通过 data 参数中的上下文信息（如 data.layout）进行判断。

第四阶段：特有行为

hexo generate

hexo generate 在生成完静态文件后会立即退出，因此第 17-18 步会在生成完成后马上触发。

hexo server

关键区别：

• hexo generate：生成后直接退出，触发 before_exit / exit
• hexo server：生成后保持运行，before_exit / exit 在手动停止时才触发
• server_middleware 是 hexo server 独有的钩子

其他独立钩子

以下钩子不属于上述主流程，但在特定场景下会被触发：

钩子使用示例

监听事件

在 Hexo 根目录的 scripts/ 文件夹中创建脚本文件：

// scripts/my-hooks.js
hexo.on('ready', function () {
  console.log('✅ Hexo 已就绪！');
});

hexo.on('generateBefore', function () {
  console.log('⏳ 开始生成静态文件...');
});

hexo.on('generateAfter', function () {
  console.log('✅ 生成完成！');
});

hexo.on('exit', function () {
  console.log('👋 Hexo 进程即将退出');
});

注册过滤器

// scripts/my-filters.js
// 在文章渲染前将标题转为小写
hexo.extend.filter.register('before_post_render', function (data) {
  data.title = data.title.toLowerCase();
  return data;
}, 10);

// 在文章渲染后替换内容中的 @用户名 为 Twitter 链接
hexo.extend.filter.register('after_post_render', function (data) {
  data.content = data.content.replace(
    /@(\w+)/g,
    '<a href="https://twitter.com/$1">@$1</a>'
  );
  return data;
}, 10);

// 在生成前执行自定义逻辑
hexo.extend.filter.register('before_generate', function () {
  console.log('⏳ 生成前执行自定义逻辑...');
});

// 修改模板局部变量
hexo.extend.filter.register('template_locals', function (locals) {
  locals.currentYear = new Date().getFullYear();
  return locals;
});

// 压缩 HTML（使用 after_render:html）
const htmlMinifier = require('html-minifier');
hexo.extend.filter.register('after_render:html', function (str, data) {
  // str: 渲染完成后的 HTML 字符串
  // data: 包含页面相关信息的对象
  // 注意：此过滤器会在每次渲染完成后执行，不仅限于完整页面
  // 可以通过 data.layout 判断是否为完整页面
  if (data.layout && data.layout !== 'false') {
    return htmlMinifier.minify(str, {
      removeComments: true,
      collapseWhitespace: true,
      minifyJS: true,
      minifyCSS: true
    });
  }
  return str;
}, 10);

过滤器优先级

优先级数字越小，执行越早：

// 优先执行（priority: 1）
hexo.extend.filter.register('after_post_render', function (data) {
  // 最先执行
  return data;
}, 1);

// 后执行（priority: 20）
hexo.extend.filter.register('after_post_render', function (data) {
  // 最后执行
  return data;
}, 20);

快速参考表

总结

1. 事件（Events） 和 过滤器（Filters） 是 Hexo 提供的两种钩子机制，分别用于监听流程节点和修改数据。
2. 核心流程：所有构建命令（generate、server）都会经历 初始化 → 处理源文件 → 生成静态文件 三个阶段。
3. 命令特有钩子：
   • hexo server 独有 server_middleware 过滤器
   • hexo deploy 独有 deployBefore / deployAfter 事件
   • hexo new 独有 new 事件和 new_post_path 过滤器
   • hexo clean 独有 after_clean 过滤器
4. after_render 过滤器家族：after_render 本身是一个过滤器类型，可细分为 after_render:html、after_render:css、after_render:js、after_render:xml 等。注册时需指定具体格式，且该过滤器会在每次渲染完成后执行，不仅限于最终页面。
5. 退出时机：hexo generate 在生成完成后立即退出；hexo server 保持运行，直到手动停止才触发退出钩子。