📚 课程目录第1章课程导入与Node-RED环境搭建

1. 课程导入与Node-RED环境搭建

在农业自动化项目中，我们经常面对这样的场景：温室里分布着温湿度、光照、土壤水分传感器，大棚外有气象站，灌溉阀门、风机、补光灯需要按条件联动。传统做法是用 PLC 或单片机写一套专用程序，逻辑一旦调整就要重新烧录、重新调试。Node-RED 提供的正是另一种思路——用浏览器里的可视化画布，把"采集—判断—执行—记录"串成一条条流程，改逻辑就像改接线图一样直观。

Node-RED 是构建在 Node.js 之上的开源流程编排工具，最初由 IBM 为物联网场景开发。它的核心模型非常简洁：节点（node）代表一个处理单元，连线（wire）代表消息流向，消息以 JSON 对象在节点间传递，通常携带 payload、topic 等字段。在农业自动化中，它常被放在"设备层"与"应用层"之间：向下通过 Modbus、MQTT、串口连接传感器与控制器，向上通过 HTTP、数据库、Dashboard 提供监控与记录。理解这一定位，后面的所有流程开发才有落脚点。

安装前的准备

Node-RED 依赖 Node.js 运行，推荐使用 Node.js 18 LTS 或 20 LTS 版本，Node-RED 4.x 对这两个版本支持最稳定。安装前先确认本机环境：

node -v
npm -v

若命令返回版本号（例如 v20.11.1 与 10.2.4），说明环境就绪；若提示"不是内部或外部命令"，需先到 Node.js 官网下载 LTS 安装包，安装时勾选加入 PATH。Windows 用户也可用 winget install OpenJS.NodeJS.LTS，macOS 用户可用 brew install node@20。

安装并启动 Node-RED

全局安装是最省事的方式，适合学习和单机部署：

npm install -g --unsafe-perm node-red
node-red

启动后终端会打印访问地址，默认是 http://127.0.0.1:1880。在浏览器打开该地址，看到带左侧节点面板、中间画布、右侧信息栏的编辑器界面，就说明安装成功。若 1880 端口被占用，可用 node-red -p 1881 换端口；若希望局域网内其他设备访问，可加 -H 0.0.0.0，但要注意此时编辑器没有登录保护，仅建议在可信内网使用。

首次启动时 Node-RED 会在用户目录下生成 .node-red 文件夹，其中的 settings.js 是全局配置文件，flows.json 保存当前流程。后续接入串口、Modbus 等硬件时，需要在这里或通过编辑器安装对应节点包，因此建议现在就记住这个目录的位置。

认识编辑器界面

编辑器由四个区域组成，理解它们的分工能显著提高后续开发效率：

节点面板（左侧）：按功能分组，common 组里有 inject、debug、function、change 等基础节点，network 组里有 mqtt、http 等通信节点。顶部搜索框可直接输入节点名过滤。
画布（中间）：拖放节点、连线、双击编辑属性的主工作区。滚轮缩放，空格键加拖动可平移。
信息栏（右侧）：包含"信息"（选中节点的说明）、"调试"（debug 输出）、"配置节点"等标签页。调试信息是排查流程的第一现场。
顶部工具栏：部署按钮（Deploy）、侧边栏开关、菜单。部署是把画布上的修改真正生效的动作，未部署的改动不会运行。

一个容易忽略的细节：画布上的流程分为"已部署"和"未部署"两种状态，节点右上角出现蓝色圆点表示有未部署的修改。农业现场调试时，改完逻辑务必确认部署成功，否则会出现"明明改了却不生效"的困惑。

第一个流程：注入—调试

下面用最小流程验证环境是否真正可用。目标很明确：让一个 inject 节点每秒产生一条带时间戳的消息，经 debug 节点输出到调试面板。

从左侧面板拖入 inject 节点到画布，双击打开属性。将 msg.payload 设为"时间戳"类型（下拉选择 timestamp），重复间隔设为 interval、1 秒，名称填"每秒心跳"。
拖入 debug 节点，双击将输出设为 msg.payload，名称填"查看心跳"。
用鼠标从 inject 节点右侧端口拖一条线到 debug 节点左侧端口。
点击右上角"部署"，然后在右侧"调试"标签页观察输出。

预期结果是调试面板每秒新增一条数字，例如 1735689600000，这是毫秒级 Unix 时间戳。若没有输出，依次检查：是否点了部署、inject 节点是否处于启用状态、调试面板是否切到了正确的标签页。这个流程虽小，却完整走通了"触发—传递—观察"的链路，后续所有农业逻辑都是在这条链路上扩展。

建议把 inject 的重复间隔先设为 1 秒做验证，确认无误后再改为实际业务需要的周期（如土壤湿度每 30 秒采集一次）。调试阶段高频触发便于观察，生产阶段则应避免无意义的高频消息占用资源。

从心跳到农业语义

把上面的流程稍作改造，就能体现农业场景的语义。将 inject 的 payload 改为 JSON 对象，模拟一条传感器读数：

{"deviceId":"soil-01","moisture":18.5,"unit":"%"}

在 inject 属性中选择 JSON 类型并填入上述内容，debug 输出改为完整消息 msg。部署后调试面板会显示对象结构，可以看到 payload.moisture 的值为 18.5。这一步的意义在于：Node-RED 中所有业务数据都以消息字段承载，后续的判断节点、函数节点都围绕这些字段工作。例如设定"土壤含水量低于 25% 触发灌溉"时，判断条件就是 msg.payload.moisture < 25。现在先把数据通路打通，条件逻辑留到后续章节展开。

常见启动问题与判断依据

安装环节最容易卡在三处。其一是 node-red 命令找不到，通常是 npm 全局目录未加入 PATH，可用 npm config get prefix 查看全局路径并手动加入。其二是启动报端口占用，终端会明确提示 EADDRINUSE，换端口即可。其三是浏览器打开空白或无法连接，先确认终端是否仍在运行、地址是否用了 127.0.0.1 而非 localhost 解析异常。判断标准很直接：终端出现 Server now running at http://127.0.0.1:1880 且浏览器能加载编辑器，环境即视为可用。

完成本节后，你应当拥有一个可正常启动的 Node-RED 环境，能说清它在农业自动化系统中的位置，并成功运行过一条注入—调试流程。这条看似简单的链路，正是后续传感器接入、阈值判断、阀门联动与数据记录的共同基础。