进阶 docs.nodebb.org 2026-10-13 15:07:09 · 31 阅读

第44章 NodeBB 可用钩子(Hooks)详解

可用钩子(Hooks)

以下是 NodeBB 中所有钩子的清单,供想为 NodeBB 开发插件的开发者参考。更多信息请查阅《为 NodeBB 编写插件》。

大多数情况下,当你想与 NodeBB 集成时,都需要挂接到 NodeBB 内部处理的某个环节。这通过我们的插件钩子系统,由插件附加一个监听器来实现。钩子分为四类:filter(过滤器)、action(动作)、static(静态)和 response(响应)钩子。

Filter 钩子

Filter 作用于内容本身,当你想在内容流经 NodeBB 时对其进行修改,filter 会非常有用。

比如,可以用 filter 把帖子中所有 "apple" 替换为 "orange"。类似地,filter 也可以用来美化内容(如代码高亮),或过滤脏话(敏感词过滤)。

NodeBB 调用 filter 钩子时,通常会以对象的形式传入一个参数,你必须按相同的结构返回数据——因为可能有多个插件在监听同一个钩子,大家预期的是同一种对象结构。我们不强制要求返回完全相同的对象,但建议这么做。

NodeBB 会按顺序执行所有已注册的监听器,等待它们全部返回数据(无论是否修改过)之后,才继续后续执行。

检查传入的数据

filter 载荷的具体结构因钩子而异,最稳妥的办法是在第一次挂接监听器时先把参数打印出来看看:

plugin.myMethod = async (data) => {
    console.log(require('util').inspect(data, { depth: 1 }));
    return data;
};

有几点需要留意:

  • 单数和复数形式的钩子,载荷结构通常不同。例如 filter:topic.get 收到的是 { topic, uid }(单个主题),而 filter:topics.get 收到的是 { topics, uid }(数组)。针对其中一个写的代码不能直接用于另一个。
  • 务必返回载荷对象——返回 undefined 会导致后续监听器和核心代码拿不到数据。
  • 要防范字段缺失,因为其他插件(或未来的核心改动)可能改变字段:if (!data || !data.topic) { return data; }。

在 filter 中报告错误

有些 filter 允许插件拒绝或否决正在进行的操作(例如在用户创建前校验用户名)。不同钩子的约定并不统一,请查看调用代码是如何消费结果的:

  • 大多数校验类 filter 期望你抛出一个错误,错误消息是一个翻译键。NodeBB 会把翻译后的消息展示给用户,并中止该操作。
plugin.checkUsernameOnCreate = async (data) => {
    // filter:user.create — 通过抛错来拒绝
    if (isReserved(data.user.username)) {
        throw new Error('[[myplugin:error.reserved-username]]');
    }
    return data;
};
  • 少数 filter 则期望你在载荷上设置 error 属性后正常返回。filter:username.check 就是这样一个钩子:
plugin.checkUsername = async (data) => {
    // filter:username.check — 通过设置 data.error 来拒绝
    if (isReserved(data.username)) {
        data.error = new Error('[[myplugin:error.reserved-username]]');
    }
    return data;
};

拿不准时,可以去 NodeBB 源码中找到该钩子的触发位置,看看它读取的是抛出的错误还是返回的 error 字段。

Action 钩子

Action 顾名思义,就是在 NodeBB 执行某个动作时被触发。如果你想在某个事件发生后异步做一些事情,action 钩子会很合适。

例如,可以用 action 钩子在特定用户发帖时通知管理员。其他用途还包括记录分析数据,或在新用户注册后自动发送欢迎帖。

Action 钩子可能携带数据载荷,也可能没有,但 NodeBB 明确不会关心监听器返回了什么(也不会使用返回的数据)。

NodeBB 会同时执行某个 action 钩子的所有已注册监听器,不会等待响应就继续执行。如果你需要 NodeBB 等待你的处理结果,应该用 filter/static 钩子。

Static 钩子

Static 钩子触发后会等待你完成某些处理再继续。它们与 action 钩子类似,区别在于 action 触发后 NodeBB 立即继续执行,而 static 钩子会给你一段时间运行自定义逻辑,之后再恢复执行。

NodeBB 会传入数据载荷,并同时执行所有已注册的监听器。它会等待所有监听器返回(或执行返回回调)之后才继续。

Response 钩子

Response 钩子按顺序执行,在此之前与 action 钩子类似。一旦某个监听器向客户端发送了响应,其后的所有插件钩子都会被完全跳过,包括核心代码的默认响应。

Response 钩子适用于一个或多个插件可能选择向客户端发送错误、或将其重定向到别处的场景。其结构设计保证了冲突可以避免。

不得不说,NodeBB 中的 response 钩子并不多。核心中唯一的一个是 response:middleware.authenticate,它允许插件向受保护的路由添加自己的认证策略。此时 NodeBB 会像中间件一样传入 req 和 res,插件可以选择响应,也可以不响应。NodeBB 会检查响应头是否已发送,如果尚未向客户端发送响应,则继续往下执行。

举例来说,用户访问受保护的路由时,NodeBB 会对未登录用户触发 response:middleware.authenticate,如果没有任何插件做出响应,就继续执行默认行为,即展示 "Not Allowed" 页面。

钩子列表

请查阅自动生成的钩子列表。该列表由 NodeBB 代码库自动生成,不保证始终完整。

特殊钩子

NodeBB 代码库中还有一些特殊钩子,没有在自动生成的钩子页面中列出。它们被收录在这里,因为要么很有用,要么脱离上下文难以理解。

页面构建钩子

除了在某些动作时执行的钩子外,每次页面加载时(无论是直接访问还是页面跳转)还会触发一组钩子:

  • filter: