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

第43章 NodeBB 插件开发指南

编写 NodeBB 插件

既然你想为 NodeBB 写插件,那太好了!在动手之前,有几件事你需要先了解清楚。

和 WordPress 类似,NodeBB 的插件也是建立在钩子系统之上。该系统以受控的方式向插件开发者暴露 NodeBB 的部分功能,允许他们在内容经过时修改内容,或在触发时执行特定行为。

如需查看更多钩子的完整列表,请参考 页面。

插件钩子

钩子共有四种类型:过滤器、动作、静态钩子和响应钩子。

* 过滤器接收一个输入参数(作为单一参数传入),以某种方式解析它,并返回修改后的值。 * 动作接收多个输入参数,并根据收到的输入执行相应操作。动作不返回任何值。 * 静态钩子与动作钩子类似,区别在于 NodeBB 会等待钩子完成(通过调用传入的回调函数)后才继续执行后续流程。 * 响应钩子与动作钩子类似,但监听器是一次性调用的;如果已向客户端发送响应,则会提前终止。

在编写插件时,请确保在你希望发生某事的位置存在相应的钩子。如果某个钩子不存在,请提交一个 Issue,我们会在下一个 NodeBB 版本中加入它。

关于钩子的更多信息,请查阅 页面。

编写插件库文件

插件的核心是库文件,一旦插件被激活,NodeBB 会自动引入该文件。

你在库中编写的每个方法接受的参数数量不同,具体取决于其调用方式:

* 过滤器会将单一参数传递给你的方法,而异步方法还可以接受一个回调函数。 * 动作会传递多个参数(具体数量取决于钩子的实现方式)。这些参数列在 列表中。

库方法示例

如果我们编写一个监听 `action:post.save` 钩子的方法,需要在插件的 `package.json` 文件的 `hooks` 部分添加如下行: ```json { "hook": "action:post.save", "method": "myMethod" } ```

我们的库代码将如下编写: ```javascript var MyPlugin = { myMethod: function(postData) { // 在这里对 postData 进行处理 } };

module.exports = MyPlugin; ```

使用 NodeBB 库增强插件

偶尔,你可能需要使用 NodeBB 的库。例如,要验证用户是否存在,就需要调用 User 类中的 exists 方法。为了让插件访问这些 NodeBB 类,请使用 require.main.require: ```javascript var User = require.main.require('./src/user'); User.exists('foobar', function(err, exists) { // ... }); ```

关于插件最常调用的核心库——包括数据库封装、用户、群组、主题、权限、通知以及控制器/路由辅助函数,以及一些常见用法示例,请参阅 Using Core Libraries。

安装插件

在绝大多数情况下,插件应该发布在 npm 上,且包名需以 "nodebb-plugin-" 为前缀。这将允许用户通过运行 npm install 直接将插件安装到他们的实例中。

通过 npm 安装时,插件名称必须以 "nodebb-plugin-" 为前缀,否则 NodeBB 将无法找到它。

在 NodeBB 包管理器 (nbbpm) 中列出插件

所有 NodeBB 实例都会从 NodeBB 包管理器(简称 nbbpm)获取可下载的插件列表。

当你创建并发布插件到 npm 时,nbbpm 会捕获该插件,但在你在插件的 package.json 中指定兼容性字符串之前,它不会出现在安装列表中。

为此,在 package.json 中创建一个名为 nbbpm 的对象,并包含一个名为 compatibility 的属性。该属性的值是一个 semver 范围,表示插件兼容的 NodeBB 版本。

你可能不知道插件兼容哪些版本,因此最好使用与你当前 NodeBB 相同的版本范围。例如,如果你正在针对 NodeBB v0.8.0 开发插件,最简单的兼容性字符串如下: ```json { ... "nbbpm": { "compatibility": "^0.8.0" } } ```

若希望插件能在多个 NodeBB 版本中安装,可使用此类字符串: ```json { ... "nbbpm": { "compatibility": "^0.7.0 || ^0.8.0" } } ```

任何有效的 semver 字符串均可使用。你可以在这个网站验证 semver 字符串的有效性: http://jubianchi.github.io/semver-check/

链接插件

在正式发布前测试插件时,可以尝试将插件链接到实例的 node_modules 文件夹中。 https://docs.npmjs.com/cli/link

在创建插件的目录(/plugins/my-plugin)下打开终端,运行: npm link

然后在 NodeBB 安装的源代码文件夹中运行: npm link my-plugin

接着需要重新构建 NodeBB: ./nodebb build

此时,你的插件应在管理面板中可用并激活。

添加自定义钩子

你可以使用 NodeBB 用于插件的同一套钩子系统来创建自定义钩子,供其他插件使用。在你的代码中引入插件库: const plugins = require.main.require('./src/plugins'); 然后在需要的位置使用 plugins.hooks.fire 命令。

通过这段代码,任何插件都可以通过监听 filter:myplugin.mymethod 对 postData 变量进行处理,就像处理普通函数一样。当所有插件处理完毕后,你可以像往常一样继续操作该变量。

```javascript var Plugins = require.main.require('./src/plugins'); var MyPlugin = { myMethod: async function(postData) { // 在这里对 postData 进行处理 const result = await plugins.hooks.fire('filter:myplugin.mymethod', { postData : postData }); // 在这里对 postData 进行更多处理 } }; ```

测试

你可以执行 ./nodebb dev 或 ./nodebb start -dl 以开发模式运行 NodeBB(其中 -l 参数会立即显示实时服务器日志,-d 表示“开发模式”)。

这会暴露插件调试日志,让你确认插件是否已加载及其钩子是否已注册。从管理面板激活插件并进行测试。

附加调试器

如果支持,你可以在插件文件中添加断点,并使用 IDE 内置的调试器进行检查。这有助于查看当前定义的信息和变量。

调试器合适的入口点是 NodeBB 安装文件夹根目录下的 app.js 文件。

禁用插件

你可以在 ACP(管理员控制面板)中禁用插件,但如果论坛因损坏的插件而崩溃,可以通过执行 ./nodebb reset -p 重置所有插件。

或者,你可以运行以下命令禁用单个插件: ./nodebb reset -p nodebb-plugin-im-broken

或 ./nodebb reset -p broken-plugin

评论 (0)