Node-RED - 从零到一：构建你的首个自定义节点

1. 初识Node-RED自定义节点开发

第一次接触Node-RED自定义节点开发时，我完全被它的灵活性震惊了。记得当时我需要频繁处理设备上报的温度数据，每次都要重复编写相同的转换逻辑，不仅效率低下还容易出错。直到发现可以把这些逻辑封装成可复用的节点，整个开发体验才彻底改变。

Node-RED本质上是一个基于流的可视化编程工具，它的核心优势在于通过拖拽节点快速构建应用。但很多人不知道的是，当内置节点无法满足需求时，我们可以自己造轮子。自定义节点就像乐高积木，把特定功能封装成标准化模块后，整个团队甚至社区都能受益。

为什么需要自定义节点？举个例子，假设你经常需要调用某个天气API获取数据并格式化输出。传统做法是在Function节点里写代码，但这样会有三个痛点：

1. 代码无法复用，每次都要复制粘贴
2. 没有可视化配置界面
3. 错误处理需要重复实现

而自定义节点能完美解决这些问题。它由三部分组成：

• JavaScript文件（核心逻辑）
• HTML文件（配置界面）
• package.json（模块描述）

我建议初学者从简单的数据转换类节点入手，比如将摄氏度转华氏度。这类节点逻辑简单但非常实用，能快速建立开发信心。当你在流程中看到自己开发的节点正常工作时，那种成就感绝对值得体验。

2. 开发环境准备

工欲善其事，必先利其器。在开始编码前，我们需要准备好开发环境。我强烈建议使用VS Code作为IDE，它的Node.js插件和调试功能对开发非常友好。

基础环境要求：

• Node.js 16.x或更高版本（建议使用LTS版本）
• npm 8.x（通常随Node.js自动安装）
• Git（用于版本控制）

安装Node-RED开发环境有两种方式：

# 全局安装（适合快速开始） npm install -g node-red # 项目本地安装（推荐用于正式开发） mkdir my-node-project && cd my-node-project npm init -y npm install node-red

目录结构规划是很多人容易忽视的点。我习惯采用如下结构：

node-red-contrib-my-nodes/ ├── nodes/ │ ├── my-node.js │ └── my-node.html ├── package.json └── README.md

这种结构清晰区分了不同类型文件，也符合Node-RED社区规范。特别提醒：节点名称建议以node-red-contrib-前缀开头，这是社区约定俗成的命名规则。

调试配置技巧： 在VS Code中创建.vscode/launch.json文件：

{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "启动Node-RED", "program": "${workspaceFolder}/node_modules/.bin/node-red", "args": ["--verbose"] } ] }

这样可以直接在IDE中启动和调试Node-RED，查看实时日志。遇到问题时，这个配置能节省大量调试时间。

3. 创建第一个功能节点

让我们从经典的字符串大小写转换节点开始。这个例子虽然简单，但包含了自定义节点的所有核心要素。

创建package.json：

npm init

按照提示填写信息后，手动添加关键配置：

{ "name": "node-red-contrib-example", "version": "1.0.0", "node-red": { "nodes": { "lower-case": "nodes/lower-case.js" } } }

编写核心逻辑（lower-case.js）：

module.exports = function(RED) { function LowerCaseNode(config) { RED.nodes.createNode(this, config); const node = this; node.on('input', function(msg, send, done) { try { if (typeof msg.payload === 'string') { msg.payload = msg.payload.toLowerCase(); send(msg); } else { node.error("Payload不是字符串类型", msg); } done(); } catch (err) { done(err); } }); } RED.nodes.registerType("lower-case", LowerCaseNode); }

这段代码有几个关键点需要注意：

1. RED.nodes.createNode初始化节点基础功能
2. node.on('input')处理传入消息
3. send(msg)发送处理后的消息
4. done()表示处理完成
5. node.error报告错误

设计配置界面（lower-case.html）：

<script type="text/javascript"> RED.nodes.registerType('lower-case', { category: 'function', color: '#a6bbcf', defaults: { name: { value: "" } }, inputs: 1, outputs: 1, icon: "font-awesome/fa-text-height", label: function() { return this.name || "转为小写"; } }); </script> <script type="text/html"># 在节点项目目录执行 npm link # 在Node-RED用户目录执行（通常是~/.node-red） npm link node-red-contrib-example

启动Node-RED开发模式：

node-red --safe-mode=false

safe-mode参数禁用安全模式，允许加载未签名的节点。

调试技巧：

1. 使用node.warn()输出调试信息到调试侧边栏
2. 在代码中添加日志点：

node.log("收到消息：" + JSON.stringify(msg));

3. 利用VS Code的调试器设置断点

常见问题排查：

• 节点不显示？检查浏览器控制台是否有加载错误
• 配置不保存？确认HTML中的>// 发送到第一个输出 send([msg1, null]); // 发送到第二个输出 send([null, msg2]);

  动态配置界面： 在HTML中使用JavaScript增强交互：

  <script type="text/javascript"> RED.nodes.registerType('advanced-node', { // ...其他配置... oneditprepare: function() { $("#node-input-type").change(function() { // 根据选择动态显示/隐藏配置项 }); } }); </script>

  状态指示：

  // 设置节点状态 node.status({fill:"green", shape:"dot", text:"已连接"}); // 清除状态 node.status({});

  外部模块依赖： 如果需要使用第三方库：

  1. 在package.json中添加依赖
  2. 在节点代码中require：

  const moment = require("moment");

  最佳实践建议：

  1. 保持节点功能单一（一个节点只做一件事）
  2. 提供清晰的错误提示
  3. 为配置项设置合理的默认值
  4. 考虑向后兼容性
  5. 编写详细的帮助文档

  6. 打包与发布

  当节点开发完成并通过测试后，就可以分享给更多人使用了。

  发布到npm：

  # 登录npm（如果没有账号需要先注册） npm login # 发布包 npm publish

  版本管理规范：

  • 主版本号（重大变更）
  • 次版本号（新增功能）
  • 修订号（问题修复）

  使用npm version命令管理版本：

  npm version patch # 1.0.0 → 1.0.1 npm version minor # 1.0.1 → 1.1.0 npm version major # 1.1.0 → 2.0.0

  发布到Node-RED库：

  1. 确保package.json包含完整元数据
  2. 编写清晰的README.md
  3. 在flows.nodered.org提交节点信息

  企业内部分享： 如果不想公开发布，可以：

  1. 打包成tgz文件：

  npm pack

  2. 通过内部npm仓库共享
  3. 直接复制节点目录到目标机器的node_modules

  7. 实战案例：API调用节点

  让我们通过一个更复杂的案例巩固所学知识 - 开发一个封装了天气API调用的自定义节点。

  设计目标：

  • 可配置API密钥和城市
  • 支持请求超时设置
  • 提供请求状态反馈
  • 格式化输出数据

  核心代码结构：

  module.exports = function(RED) { const axios = require("axios"); function WeatherNode(config) { RED.nodes.createNode(this, config); const node = this; this.apiKey = config.apiKey; this.city = config.city; this.timeout = parseInt(config.timeout) || 5000; node.on('input', async function(msg, send, done) { try { node.status({fill:"blue", shape:"dot", text:"请求中..."}); const response = await axios.get( `https://api.weatherapi.com/v1/current.json?key=${node.apiKey}&q=${node.city}`, { timeout: node.timeout } ); msg.payload = { temperature: response.data.current.temp_c, condition: response.data.current.condition.text, lastUpdated: new Date(response.data.current.last_updated) }; node.status({fill:"green", shape:"dot", text:"请求成功"}); send(msg); done(); } catch (err) { node.status({fill:"red", shape:"ring", text:"请求失败"}); node.error("API请求错误: " + err.message, msg); done(err); } }); } RED.nodes.registerType("weather-api", WeatherNode); }

  高级配置界面：

  <script type="text/javascript"> RED.nodes.registerType('weather-api', { category: 'function', color: '#37B6E9', defaults: { name: { value: "" }, apiKey: { value: "", required: true }, city: { value: "北京", required: true }, timeout: { value: 5000, validate: RED.validators.number() } }, credentials: { apiKey: { type: "password" } }, inputs: 1, outputs: 1, icon: "font-awesome/fa-cloud", label: function() { return this.name || "天气API"; } }); </script> <script type="text/html">